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, archive 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.

Archiving an Entity

Archive an entity when it should stop appearing in your marketing, but you want to keep its history. For example, a pet that has passed away, or one the customer asked you to stop emailing about.

To archive, open the entity from the customer’s profile or subscription and click Archive.

What archiving does

• Removes the entity from your integrations. If you sync entities to Klaviyo, its Klaviyo record is deleted, so it drops out of Klaviyo segments and flows.
• Locks the entity. Nobody can edit it, in the dashboard, the customer portal or the API, until it is unarchived.
• Marks it Archived everywhere it appears in Gro, so your team can see it at a glance.

What archiving doesn’t do

• It doesn’t delete anything in Gro. The entity, its attributes and its history stay.
• It doesn’t touch subscriptions. Products assigned to the entity stay assigned, and orders keep shipping. Change or cancel the subscription separately if you need to.

Unarchiving

Click Unarchive on the entity. It can be edited again, and if you sync to Klaviyo, Gro sends it back with its current name and attributes. Klaviyo treats it as a new record, so anything Klaviyo stored only on the old record isn’t restored.

Note

If the customer signs up for a new pet with the same name as an archived one, Gro creates a new entity instead of reusing the archived one.

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
archived	boolean	true for archived entities only, false to leave them out
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
  }
}

Archive Entity

POST /api/entities/:id/archive

Archiving keeps the entity in Gro but removes it from your integrations. If you sync entities to Klaviyo, its Klaviyo record is deleted. Use it when a pet passes away or a customer no longer wants it on file, but you still want the history in Gro.

To send it back to your integrations:

POST /api/entities/:id/unarchive

Both return the entity, with archived_at set while it is archived. Updating an archived entity returns 422 until it is unarchived. See Archiving an Entity for exactly what changes.

Delete Entity

DELETE /api/entities/:id

Deleting also removes the entity from your integrations.

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