Manage Stores

These endpoints allow you to create, read, update, and delete stores for a merchant via the API.

Authentication

All requests require HTTP Basic Auth using your API account credentials:

Authorization: Basic base64(username:password)

The API account must be scoped to the target merchant

List stores

Returns all stores belonging to the merchant.

Endpoint: /api/public/v1/merchants/{merchant_ref}/stores

Method: GET

Response

[
  {
    "id": 7,
    "reference": "store-bcn-01",
    "name": "Barcelona Store",
    "active": true,
    "orders_count": 142,
    "users_count": 3,
    "user_authorizations": [
      {
        "id": 42,
        "email": "[email protected]",
        "name": "Jane Doe"
      }
    ],
    "created_at": "2025-06-01T10:00:00.000Z"
  }
]

Get a store

Endpoint: /api/public/v1/merchants/{merchant_ref}/stores/{reference}

Method: GET

Response

{
  "id": 7,
  "reference": "store-bcn-01",
  "name": "Barcelona Store",
  "active": true,
  "orders_count": 142,
  "users_count": 3,
  "user_authorizations": [
    {
      "id": 42,
      "email": "[email protected]",
      "name": "Jane Doe"
    }
  ],
  "created_at": "2025-06-01T10:00:00.000Z"
}

Create a store

Endpoint: /api/public/v1/merchants/{merchant_ref}/stores

Method: POST

Payload

{
  "reference": "store-bcn-02",
  "name": "Barcelona Store 2",
  "address": "Carrer de Mallorca 456",
  "city": "Barcelona",
  "postal_code": "08013",
  "store_phone": "934 000 000",
  "store_email": "[email protected]",
  "active": true
}

Field explanation

Field	Type	Required	Description
`reference`	string	Yes	Unique identifier for the store within the merchant. Used in subsequent requests to identify the store.
`name`	string	Yes	Display name of the store.
`address`	string	No	Street address.
`city`	string	No	City name.
`postal_code`	string	No	Postal / ZIP code.
`store_phone`	string	No	Contact phone number for the store.
`store_email`	string	No	Contact email address for the store.
`active`	boolean	No	Whether the store is active. Defaults to `true`.

Response

HTTP 201 Created

{
  "id": 8,
  "reference": "store-bcn-02",
  "name": "Barcelona Store 2",
  "active": true,
  "orders_count": 0,
  "users_count": 0,
  "user_authorizations": [],
  "created_at": "2026-05-04T09:00:00.000Z"
}

Error response

{
  "errors": "Reference has already been taken"
}

Update a store

Applies a partial update (PATCH semantics) — only the fields you include are changed.

Endpoint: /api/public/v1/merchants/{merchant_ref}/stores/{reference}

Method: PUT

Payload

{
  "name": "BCN Flagship Store",
  "active": false
}

All fields from the create payload are accepted. Omitted fields are left unchanged.

Response

HTTP 200 OK — returns the updated store object (same format as GET).

Error response

{
  "errors": "Name can't be blank"
}

Delete a store

Endpoint: /api/public/v1/merchants/{merchant_ref}/stores/{reference}

Method: DELETE

Response

HTTP 200 OK (empty body)

Error response

{
  "errors": "Cannot delete store with active subscriptions"
}