Entities

Entities are an optional but powerful feature that let you connect named recipients — people, pets, children, or anything else — to a subscription. A single customer can manage multiple subscriptions under one account, each personalised for a different entity.

Why Entities?

Many subscription businesses serve products that aren’t just for the purchaser. A customer might be buying for their dogs, their kids, or family members. Without entities, this customer would need separate accounts or manually track which subscription is for whom.

With entities, a single profile can manage it all:

• Pet food brand — One customer subscribes for “Max” (large breed, 5 years, chicken allergy) and “Bella” (small breed, 1 year, no allergies)
• Kids vitamins — A parent manages subscriptions for “Emma” (age 8, gummy preference) and “James” (age 12, tablet preference)
• Gift subscriptions — One account manages monthly coffee boxes for “Mum”, “Dad”, and “Sarah”

Each subscription displays a friendly label so the customer always knows who it’s for — “Max”, “Max and Bella”, or “Max, Bella and Charlie”.

How Entities Work

Entities are linked to a Profile (your customer record in Gro). You can view and manage a customer’s entities from their profile in the dashboard.

Each entity has:

Field	Description
Name	Display name (e.g. “Max”, “Emma”)
Entity type	A label for the kind of entity (e.g. “dog”, “cat”, “child”, “person”)
Attributes	Any custom properties you want to store
Image	Optional display image
Active	Whether the entity is currently active

Custom Attributes

Entities support completely flexible attributes — you can store any properties that are relevant to your business. Attributes are key-value pairs that can hold strings, numbers, booleans, or arrays.

Examples by entity type:

Entity Type	Example Attributes
Dog	breed, weight, age, allergies, activityLevel, foodPreference
Cat	breed, weight, indoorOutdoor, allergies, age
Child	birthDate, gender, clothingSize, interests, favouriteColour
Person	shirtSize, dietaryRestrictions, favouriteScent

There are no restrictions on what you store — define whatever attributes make sense for your product and use them to drive personalisation, product recommendations, or filtering in the Build-a-Box wizard.

Entities and Subscriptions

Entities connect to subscriptions at two levels:

1. Subscription level — An entity is linked to the overall subscription (e.g. “This subscription is for Max”)
2. Line item level — Individual products within a subscription can be assigned to specific entities (e.g. “This kibble is for Max, these treats are for Bella”)

A subscription can have multiple entities linked to it. One entity is marked as the primary entity for display purposes.

This is especially powerful with Build-a-Box — customers can build separate boxes for each entity, all managed under a single subscription.

Managing Entities in the Dashboard

Entities are managed from the Profile view in the Gro dashboard:

1. Navigate to a customer’s profile
2. View their entities in the entities section
3. Create, edit, or deactivate entities as needed

From here you can see all entities associated with the customer, their attributes, and which subscriptions they’re linked to.

Entities via the API

Entities are fully managed through the Gro API at https://api.usegro.co.

List Entities

GET /api/entities

Query parameters:

Parameter	Type	Description
profile_id	string	Filter by customer profile
entity_type	string	Filter by type (e.g. “dog”)
is_active	boolean	Filter by active status
page	number	Page number
limit	number	Results per page (max 100)
sort_by	string	Sort field: created_at, name, or entity_type
sort_order	string	asc or desc

Get Entity

GET /api/entities/:id

Create Entity

POST /api/entities

{
  "profile_id": "01234567-89ab-cdef-0123-456789abcdef",
  "entity_type": "dog",
  "name": "Max",
  "attributes": {
    "breed": "Golden Retriever",
    "weight": 30,
    "age": 5,
    "allergies": ["chicken"],
    "activityLevel": "high"
  },
  "image_url": "https://example.com/max.jpg",
  "is_active": true
}

Update Entity

PUT /api/entities/:id

{
  "name": "Max",
  "attributes": {
    "weight": 32,
    "age": 6
  }
}

Delete Entity

DELETE /api/entities/:id

All endpoints require API key authentication. See Authentication for details.