Create the Subscription solicitation
This is the initial request to the service. It will include the personal data and the cart items. There are two kind of items:
- material_subscription, that are single / static items: sunglasses or any non-customized items
- subscription_package: that may consist of a frame and 2 lenses, or a set of glasses.
The request for a new subscription solicitation is a POST call using JSON content.
Endpoint: /api/public/v1/subscriptions
Method: POST
Swagger https://docs.sequra.com/update/reference/post_api-public-v1-subscriptions#/
Shopper confirmation
This endpoint will only create a solicitation. Yet, the shopper will have to go through the checkout process to confirm the subscription. You must wait for a webhook to get the confirmation of the operation.
Payload example:
{
"merchant": {
"id": "tienda_moderna",
"store_ref": "tienda_moderna"
},
"reference": "ref001-5",
"operator_ref": "[email protected]",
"cart_items": [
{
"reference": "glasses1",
"type": "material_subscription",
"name": "Progressive Glasses",
"quantity": 1,
"price_with_tax": 35000,
"subscription_vat_rate": 2100,
"product_type": "rx"
},
{
"quantity": 1,
"type": "subscription_package",
"name": "Glasses Package",
"price_with_tax": 75000,
"subscription_vat_rate": 2100,
"items": [
{
"reference": "frame1",
"type": "material_subscription",
"name": "Designer Frame",
"quantity": 1,
"price_with_tax": 40000,
"subscription_vat_rate": 2100,
"product_type": "rx"
},
{
"reference": "lenses1",
"type": "material_subscription",
"name": "Anti-glare Lenses",
"quantity": 1,
"price_with_tax": 35000,
"subscription_vat_rate": 2100,
"product_type": "rx"
}
]
}
],
"given_names": "John",
"surnames": "Doe Jr",
"joint_customer": "Jane Doe",
"mobile_phone": "679959234",
"email": "[email protected]",
"date_of_birth": "2000-12-20",
"nin": "12345678Z",
"address": "C falsa, 123",
"postal_code": "01234",
"city": "Barcelona",
}
Field explanation
| Field Path | Format | Example | Description |
|---|---|---|---|
| merchant.id | String | merchant_1 | Provided by sequra’s onboarding team |
| merchant.store_ref | String | store_abc | Shared with seQura’s onboarding team |
| operator_ref | [email protected] | Shared with seQura’s onboarding team | |
| reference | String | pos_1234 | Internal id generated at Merchant’s PoS |
| price_with_tax (and any other price property) | Integer | 35000 | Price in cents. 350.00€ |
| subscription_vat_rate (and any other rate property) | Integer | 2100 | Percentage multiplied by 100 = 21.00% |
Checkout our swagger documentation for more details on the payload fields
Discounts and Promotions
Discounts vs. promotionsA discount is per line and permanent — it reduces one cart line's price for the entire
subscription. A promotion is subscription-wide and time-boxed. A top-leveldiscountsarray withstart_monthandperiod_in_monthsthat lowers the whole plan's monthly rent for a window. The two are independent and may be combined.
Using promotions
The merchant may want to apply a Discount/Promotion to the visual plan. We offer two different promotional discounts, by total amount or by percentage. The merchant can select from what month it applies and the duration. The resultant value will be discounted to both the Shopper and the Merchant, however, Sequra will charge the subscription fee to the Shopper even when the monthly rent is 0.
Payload:
{
...,
"discounts": [
{
"promotion_reference": "FULL_DISCOUNT_FIRST_MONTH",
"type": "percent",
"amount": 10000,
"start_month": 1,
"period_in_months": 1
}
]
}
Or
{
...,
"discounts": [
{
"promotion_reference": "FIXED_DISCOUNT_FIRST_MONTH",
"type": "amount",
"amount": 1500,
"start_month": 1,
"period_in_months": 1
}
]
}
Applying a discount
A discount lowers the price of a single cart line for the whole life of the subscription. Send it as a nested discount object on the item. For a package, put the discount on each per-eye contact_lens_subscription child, not on the package itself .A package's price is always the sum of its children, so discounting the children discounts the package.
seQura receives the pre-discount price and the discount, prices the line on its total, and
returns both the original and the discounted figures (see Response).
Cart items
{
"cart_items": [
{
"reference": "PKG-100",
"name": "Equipment package",
"price_with_tax": 120000,
"quantity": 1,
"type": "subscription_package",
"items": [
{
"reference": "MAT-A-100",
"type": "material_subscription",
"name": "Frame",
"price_with_tax": 48000,
"quantity": 1,
"discount": { "type": "percent", "amount": 2500 }
},
{
"reference": "MAT-B-100",
"type": "material_subscription",
"name": "Lenses",
"price_with_tax": 72000,
"quantity": 1,
"discount": { "type": "fixed_amount", "amount": 12000 }
}
]
}
]
}Priced over the 24-month subscription_period:
MAT-A-100— 25% off: total480,00 €→360,00 €; monthly20,00 €→15,00 €.MAT-B-100—120,00 €off: total720,00 €→600,00 €; monthly30,00 €→25,00 €.PKG-100(rolled up) — total1.200,00 €→960,00 €; monthly50,00 €→40,00 €.
The same discount object works on any subscription line, also contact lenses. The only
difference is the period: exchange_cycle (12 months) instead of subscription period. Below, a package of two contact_lens_subscription items — one discounted by percentage, one by a fixed amount.
{
"cart_items": [
{
"reference": "PKG-001",
"name": "Contact lens package",
"price_with_tax": 50000,
"quantity": 1,
"type": "subscription_package",
"items": [
{
"reference": "CL-LEFT-001",
"type": "contact_lens_subscription",
"name": "Left contact lens",
"price_with_tax": 25000,
"quantity": 1,
"box_count": 4,
"product_type": "contact_lenses",
"product_data": { "eye": "left" },
"discount": { "type": "percent", "amount": 2000 }
},
{
"reference": "CL-RIGHT-001",
"type": "contact_lens_subscription",
"name": "Right contact lens",
"price_with_tax": 25000,
"quantity": 1,
"box_count": 4,
"product_type": "contact_lenses",
"product_data": { "eye": "right" },
"discount": { "type": "fixed_amount", "amount": 2500 }
}
]
}
]
}For the payload above (each lens priced over a 12-month exchange cycle):
CL-LEFT-001— 20% off: total250,00 €→200,00 €; monthly20,83 €→16,67 €.CL-RIGHT-001—25,00 €off: total250,00 €→225,00 €; monthly20,83 €→18,75 €.PKG-001(rolled up) — total500,00 €→425,00 €; monthly41,66 €→35,42 €.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
discount | object | no | Line discount. Omit it for no discount. |
discount.type | string | yes | Required when discount is present. One of "percent", "fixed_amount", or "fixed_price". |
discount.amount | integer | yes | Required when discount is present. For percent: basis points (2000 = 20%, 10000 = 100%). For fixed_amount: the amount subtracted from the line total, in cents. For fixed_price: the final line total, in cents. |
price_with_tax is the line total over the whole subscription (before any discount).
SeQura applies the discount to that total, then divides by the billing period to obtain the monthly
price — the exchange cycle for contact lenses (12 months by default), or thesubscription_period (24 months) for other subscription items. A percent over 10000(100%), or a fixed_amount greater than the line total, is rejected.
Response
Each cart line comes back with both the pre-discount and the discounted values:
| Field | Description |
|---|---|
original_price_with_tax | Line total before the discount. |
total_with_tax | Line total after the discount (this is what is billed). |
original_subscription_price | Monthly price before the discount (original total ÷ period). |
subscription_price | Monthly price after the discount (discounted total ÷ period). |
discount | The { type, amount } that was applied, or null when there is none. |
Regional differences
For Mexican merchants surnames must be sent in 2 separated fields and additionaly colony field is added to address:
{
...,
"given_names": "Juan",
"first_surname": "García",
"second_surname": "López",
"date_of_birth": "1990-05-15",
"nin": "GALJ900515HDFXPN09",
"address": "Av. Insurgentes Sur 123",
"postal_code": "06600",
"city": "Ciudad de México",
"colony": "Juárez",
"joint_customer": "María García"
}
Creation Response sample
{
"id": 7,
"created_at": "2025-07-23T12:31:49.651Z",
"activated_at": null,
"renewal_at": null,
"current_month": 0,
"total_months": 24,
"customer": {
"given_names": "Iván",
"surnames": "Cinque Junior",
"email": "",
"phone": null,
"full_name": "Iván Cinque Junior"
},
"status": "draft",
"payment_status": "paid",
"reference": "ref001-5",
"available_actions": {
"cancel": false,
"withdraw": true,
"resend_sms": true,
"add_product": false,
"change_item": false,
"activate_product": false,
"use_warranty": false,
"update_customer_info": false,
"update_payment_info": false,
"change_graduation": false,
"reset_sms_count": false,
"receive_gift_kit": false,
"extend_period": false
},
"credit_card": null,
"credit_card_type": null,
"contract_number": null,
"discounts": null,
"confirmed_at": null,
"last_delivery_date": null,
"next_delivery_date": null,
"gift_kits_remaining": 4,
"gift_kits_delivered": 0,
"last_persisted_cart": {
"id": 7,
"reference": "ref001-5",
"code": "V9xHtx513GMqDNct",
"cart_items": [
{
"id": "74c1c0e9-8966-4156-a46d-7605a2dec81e",
"type": "material_subscription",
"reference": "glasses1",
"reference_uuid": "e7342263-c0f3-41f3-b0a1-0e307fc39588",
"name": "Progressive Glasses",
"price_with_tax": {
"value": 35000,
"string": "350,00 €"
},
"quantity": 1,
"total_with_tax": {
"value": 35000,
"string": "350,00 €"
},
"status": "pending",
"activated_at": "",
"subscription_price": {
"value": 1458,
"string": "14,58 €"
},
"discount_type": null,
"discount_amount": null,
"original_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"original_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"catalogue_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"catalogue_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"line_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"line_subscription_price": {
"value": 0,
"string": "0,00 €"
}
},
{
"id": "91fca517-db0d-41b1-8f8b-dc51a57761c9",
"type": "subscription_package",
"reference": null,
"reference_uuid": "c61594e3-3a32-45ff-82f9-5c92b1cc52d6",
"name": "Glasses Package",
"price_with_tax": {
"value": 75000,
"string": "750,00 €"
},
"quantity": 1,
"total_with_tax": {
"value": 75000,
"string": "750,00 €"
},
"status": "pending",
"activated_at": "",
"subscription_price": {
"value": 3125,
"string": "31,25 €"
},
"discount_type": null,
"discount_amount": null,
"original_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"original_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"catalogue_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"catalogue_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"line_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"line_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"items": [
{
"id": "a34bc81b-d8e8-48cf-9500-ee5d726e28bb",
"type": "material_subscription",
"reference": "frame1",
"reference_uuid": null,
"name": "Designer Frame",
"price_with_tax": {
"value": 40000,
"string": "400,00 €"
},
"quantity": 1,
"total_with_tax": {
"value": 40000,
"string": "400,00 €"
},
"status": "pending",
"activated_at": "",
"subscription_price": {
"value": 1667,
"string": "16,67 €"
},
"discount_type": null,
"discount_amount": null,
"original_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"original_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"catalogue_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"catalogue_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"line_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"line_subscription_price": {
"value": 0,
"string": "0,00 €"
}
},
{
"id": "277cf119-9981-40a3-8a68-a2acd2568b46",
"type": "material_subscription",
"reference": "lenses1",
"reference_uuid": null,
"name": "Anti-glare Lenses",
"price_with_tax": {
"value": 35000,
"string": "350,00 €"
},
"quantity": 1,
"total_with_tax": {
"value": 35000,
"string": "350,00 €"
},
"status": "pending",
"activated_at": "",
"subscription_price": {
"value": 1458,
"string": "14,58 €"
},
"discount_type": null,
"discount_amount": null,
"original_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"original_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"catalogue_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"catalogue_subscription_price": {
"value": 0,
"string": "0,00 €"
},
"line_price_with_tax": {
"value": 0,
"string": "0,00 €"
},
"line_subscription_price": {
"value": 0,
"string": "0,00 €"
}
}
]
}
],
"sms_mobile_phone": "679959234",
"status": "pending",
"total_with_tax": {
"value": 160000,
"string": "1.600,00 €"
},
"meta": {},
"created_at": "2025-07-23T12:31:49.488Z",
"discount": {
"value": 0,
"string": "0,00 €"
},
"other_payment": null,
"cart_handling": null,
"cart_registration": null,
"setup_fee": null,
"desired_first_charge_on": null,
"solicitation": null,
"installments_count": null,
"operator_ref": "[email protected]",
"resettable": false,
"can_reset": false,
"can_resend_sms": true,
"customer_data": {
"given_names": "Iván",
"surnames": "Cinque Junior",
"nin": "12345678Z",
"email": "",
"phone": "",
"dob": "2000-12-20"
},
"order_uuid": null,
"subscription_id": 7,
"withdrawable_subscription": true,
"currency": "EUR"
},
"subscription_events": [
{
"id": "d697a495-3a34-441d-a484-a32878a45ef1",
"subscription_id": 7,
"type": "subscription_created",
"data": {
"cart_id": 7
},
"created_at": "2025-07-23T12:31:49.710Z"
}
]
}Updated 9 days ago