Subscription available_actions

Every subscription returned by the seQura Eyewear public API includes an available_actions object. This is a map of action_key → boolean that tells perations are currently permitted on the subscription, given its state, payment status and merchant configuration.

Drive your UI from these booleans — do not replicate the rules client-side. The backend computes them taking into account the subscription lifecycle, annual quotas, gift-kit allowances and time-based windows.

Action catalogue

Action key	Meaning
`withdraw`	The subscription can be terminated. Call `POST /api/public/v1/subscriptions/{id}/cancel`; the backend automatically applies the correct flow (early withdrawal if no products were delivered yet, or full cancellation otherwise).
`send_sms`	The confirmation SMS can be sent to the customer for the first time so they can sign the contract. Used during the initial creation flow, before payment.
`resend_sms`	A new confirmation SMS can be re-sent to the customer (e.g. the customer did not receive the original one, or payment has not been confirmed yet).
`send_cart_link_email`	The confirmation link can be delivered to the customer by email — fallback when SMS is not an option.
`reset_sms_count`	The SMS attempt counter can be reset, allowing additional SMS resends after the per-cart limit has been reached.
`add_product`	A new product (extra pair of glasses, contact lenses, etc.) can be added to the existing active subscription.
`change_item`	An existing product can be swapped for a different one (e.g. different model). Consumes one unit of the annual exchange quota configured for the merchant.
`change_graduation`	The optical prescription (graduación) of a product can be updated. Specific to eyewear and contact lenses.
`use_warranty`	A warranty / coverage claim can be filed against a product (damage, loss or theft). Triggers the warranty replacement flow. Not applicable to consumable products like contact lenses.
`activate_product`	A product that has been added or delivered can be confirmed and marked as fulfilled.
`receive_gift_kit`	A gift kit delivery (e.g. contact-lens cleaning kit) can be registered for the customer. Counts against the merchant's gift-kit allowance for the current period.
`extend_period`	The subscription duration can be extended beyond its original end date.

Reserved (always `false` today)

These keys are present in the response schema for forward compatibility, but are not actionable through the public API at this time:

Action key	Meaning
`cancel`	Reserved. Use `withdraw` to terminate a subscription.
`update_customer_info`	Reserved. Customer data updates are not available through the public API.
`update_payment_info`	Reserved. Payment-method updates are not available through the public API.
`resend_to_simba`	Internal-only. Re-pushes the subscription to seQura's core system; not part of the merchant integration surface.

Integrators should treat any action they don't explicitly support as ignorable.

Sample response

{
  "id": "sub_01HF2K3MZP9X4ABC",
  "state": "active",
  "payment_status": "paid",
  "created_at": "2026-06-11T10:32:00Z",
  "activated_at": "2026-06-12T08:15:00Z",
  "customer": {
    "first_name": "María",
    "last_name": "García",
    "email": "[email protected]"
  },
  "cart_items": [
    {
      "reference_uuid": "0f5d3a64-7c91-4d2d-9e7e-2c10f8a4b001",
      "type": "subscription_package",
      "quantity": 1,
      "price_with_tax": 50000,
      "product_data": {
        "internal_note": "Cliente prefiere recoger en tienda"
      },
      "items": [
        {
          "reference": "POLAROID-PLD-D405-807",
          "description": "POLAROID PLD D405 - 807 - BLACK - 55 MM",
          "quantity": 1,
          "price_with_tax": 11640
        }
      ]
    }
  ],
  "available_actions": {
    "withdraw": true,
    "send_sms": false,
    "resend_sms": false,
    "send_cart_link_email": false,
    "reset_sms_count": false,
    "add_product": true,
    "change_item": true,
    "change_graduation": true,
    "use_warranty": true,
    "activate_product": false,
    "receive_gift_kit": true,
    "extend_period": false,

    "cancel": false,
    "update_customer_info": false,
    "update_payment_info": false,
    "resend_to_simba": false
  }
}

In the example above, the subscription is active and paid: the merchant can terminate it (withdraw), maintain its products (add_product, change_item, change_graduation, use_warranty), and deliver a gift kit (receive_gift_kit). The SMS/email actions are not applicable because the contract was already signed.

Action catalogue

Reserved (always false today)

Sample response

Reserved (always `false` today)