Update Store

Sparse-update store-level checkout setup: payment-method enablement and order, popup embed hostnames, abandoned-cart recovery defaults, VAT / flat / GTU / exempt defaults, partner defaults, and the store legal footer. Only the keys you send are changed. Unknown keys — including profile fields such as name or logo_url — return 422.

Omitted keys are unchanged. A patch applies as a whole: when any part of it is rejected, nothing in it is written. Behaviour for each section is on the Store index.

Request

PATCH /store

Request Body

All fields optional. Omit a key to leave it unchanged.

Parameter	Type	Required	Description
`payment_methods`	array	No	Sparse-by-`id` list. Unlisted methods are unchanged. See Payment methods.
`payment_methods[].id`	string	Yes, when the item is sent	Catalog key. Duplicate or unknown `id` returns `422`.
`payment_methods[].is_enabled`	boolean	No	Omit to leave this method's enablement unchanged. `true` for a method the store has not activated returns `422` — see Payment methods.
`payment_methods[].order`	integer	No	Display order, lower first. Minimum 0. Omit to leave unchanged.
`popup_allowed_domains`	array	No	Replace-all hostnames. `[]` clears. See Popup allowed domains.
`checkout_recovery`	object	No	Sparse-merges `enabled`. Sending `coupon` replaces the pair; `coupon: null` clears. See Checkout recovery.
`checkout_recovery.enabled`	boolean	No	Store-wide recovery switch.
`checkout_recovery.coupon`	object	No	`{ "amount": 500, "percent": null }` or `{ "amount": null, "percent": 10 }`, or `null` to clear. Do not send `currency`.
`vat_rate`	string	No	Store default VAT rate. `null` clears. See Tax defaults.
`flat_rate`	number	No	Store default flat-rate tax percent. `null` clears.
`gtu_code`	integer	No	Store default GTU code 1–13. `null` clears.
`exempt_tax_kind`	string	No	Store default exemption basis. `null` clears.
`partners`	object	No	Sparse partner defaults. One key leaves the other in place. See Partners.
`partners.cookie_valid_days`	integer	No	Days, 1–3650. `null` returns `422`.
`partners.commission_percent`	integer	No	Integer 1–100. `20` means 20%. `null` returns `422`. Send `commission_percent`, not `commission`.
`footer_id`	string	No	Store legal footer UUID. Saved immediately. Omit to leave the current footer. Setting a UUID turns the store legal footer on. `null` clears it and turns that footer off. Omitted from this response. Get store returns it only with `include=footer_id`. A value that is not a UUID, an unknown project, or a project that is not a legal footer on your account returns `422`, and nothing in the patch is saved. Easytools unavailable returns `502`. An account not connected to Easytools returns `422`. Neither reports `footer_id` as invalid.

Do not send provider or is_available on payment methods.

Example Requests

Enable a method and set a recovery coupon:

curl -X PATCH "https://cart.easy.tools/api/v1/store" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_methods": [
      { "id": "card", "is_enabled": true, "order": 1 },
      { "id": "blik", "is_enabled": true, "order": 2 }
    ],
    "popup_allowed_domains": ["app.example.com", "preview.example.com"],
    "checkout_recovery": {
      "enabled": true,
      "coupon": { "amount": 500, "percent": null }
    },
    "vat_rate": "23"
  }'

Clear the recovery coupon only:

curl -X PATCH "https://cart.easy.tools/api/v1/store" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_recovery": {
      "coupon": null
    }
  }'

Set the store legal footer. It is saved immediately and is not on the response:

curl -X PATCH "https://cart.easy.tools/api/v1/store" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "footer_id": "1f6b8e24-9c30-4a57-b2d8-7e4a0c5f3b91"
  }'

Clear it and turn the store legal footer off:

curl -X PATCH "https://cart.easy.tools/api/v1/store" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "footer_id": null
  }'

Change the store commission and leave the cookie length as it is:

curl -X PATCH "https://cart.easy.tools/api/v1/store" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partners": {
      "commission_percent": 15
    }
  }'

cookie_valid_days stays at its current value (7 until you change it). commission_percent becomes 15. The envelope below is the first example, which does not send partners, so those defaults are still 7 and 20.

Response

Success Response (200)

The same envelope as Get Store without include. footer_id is omitted. See Store Object.

{
  "store": {
    "id": "22b65ad7-ef20-4d46-9f04-110eba99cc77",
    "name": "Acme",
    "slug": "acme",
    "email": "store@example.com",
    "website_url": "https://mysite.com",
    "logo_url": "https://cdn.example.com/logo.png",
    "tax_id": "12-3456789",
    "company_name": "Acme Inc.",
    "full_name": "John Doe",
    "phone": "+1 212 555 0100",
    "address": {
      "street": "Main Street",
      "street_number": "123",
      "house_number": "4",
      "post_code": "10001",
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "created_at": "2024-01-10T08:00:00+00:00",
    "payment_methods": [
      {
        "id": "card",
        "provider": "stripe",
        "is_enabled": true,
        "order": 1,
        "is_available": true
      },
      {
        "id": "blik",
        "provider": "stripe",
        "is_enabled": true,
        "order": 2,
        "is_available": true
      }
    ],
    "popup_allowed_domains": ["app.example.com", "preview.example.com"],
    "checkout_recovery": {
      "enabled": true,
      "coupon": {
        "amount": 500,
        "percent": null
      }
    },
    "vat_rate": "23",
    "flat_rate": null,
    "gtu_code": null,
    "exempt_tax_kind": null,
    "partners": {
      "cookie_valid_days": 7,
      "commission_percent": 20
    }
  },
  "currencies": ["usd", "eur"]
}

Error Responses

Validation Error (422 Unprocessable Entity)

Unknown top-level key:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is not allowed."
    ]
  }
}

Enabling a method the store has not activated:

{
  "message": "The given data was invalid.",
  "errors": {
    "payment_methods.0.is_enabled": [
      "This payment method is not available."
    ]
  }
}

A hostname with a scheme:

{
  "message": "The given data was invalid.",
  "errors": {
    "popup_allowed_domains.0": [
      "Enter valid domain (e.g. mydomain.com, without http:// or https://)"
    ]
  }
}

Both coupon amount and percent:

{
  "message": "The given data was invalid.",
  "errors": {
    "checkout_recovery.coupon": [
      "Provide either amount or percent, not both."
    ]
  }
}

partners.commission is not a field. An empty partners object, or null on either key, also returns 422.

{
  "message": "The given data was invalid.",
  "errors": {
    "partners.commission": [
      "The partners.commission field is not allowed."
    ]
  }
}

{
  "message": "The given data was invalid.",
  "errors": {
    "partners.commission_percent": [
      "The partners.commission_percent field cannot be null."
    ]
  }
}

Duplicate id, unknown catalog id, provider or is_available on write, coupon.currency, and invalid tax values also return 422 on that path.

A footer_id that is not a UUID, an unknown project, or a project that is not a legal footer on your account returns 422, and nothing in the patch is saved. Easytools unavailable returns 502. An account not connected to Easytools returns 422. Neither reports footer_id as invalid.

{
  "message": "The given data was invalid.",
  "errors": {
    "footer_id": [
      "The selected footer_id is invalid."
    ]
  }
}

Service Unavailable (502)

Returned when Easytools is temporarily unavailable while attaching the store legal footer. Retry shortly. The identifier was not rejected. Nothing in the patch is saved.

{
  "message": "The Easytools service is temporarily unavailable. Please retry."
}

Account Not Connected (422)

Returned when the account is not connected to Easytools, so a footer cannot be attached. This is not an invalid footer_id. Nothing in the patch is saved.

{
  "message": "Account is not connected to Easytools"
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}

Forbidden Error (403)

Returned when the selected store has not granted you API access — see Store selection.

{
  "message": "You do not have API access to the requested store."
}

Request​

Request Body​

Example Requests​

Response​

Success Response (200)​

Error Responses​

Validation Error (422 Unprocessable Entity)​

Service Unavailable (502)​

Account Not Connected (422)​

Unauthorized Error (401)​

Forbidden Error (403)​