Order Update API Payload and Examples

Next you can find the complete list of fields you may use in the payload. If you prefer, you can directly Go to the JSON examples.

Field Mandatory? Description
merchant Yes Fields describing the merchant.
.id Yes Merchant identifier. Also called merchant_ref. Example: "s1". (string or int)
.store_ref ** Permanent identifier for the store where the checkout takes place. Example: "maquinista". (string)
** Mandatory for multistore merchants and physical stores, not permitted for others.
merchant_reference Yes Order id(s) used by the merchant
.order_ref_1 Yes Merchant reference 1. Example: "ZXCV1234". (string or int)
.order_ref_2 No Merchant reference 2. Example: "0080-1234-4343-5353". (string or int)
unshipped_cart Yes Fields describing the unshipped items.
.currency Yes Currency code for all money amounts. Example: "EUR". (string)
.order_total_with_tax Yes Total value with tax of the items listed below. Example: 6097. (int)
.items Yes List of unshipped items in the order. The list can contain zero or more instances of each item type. (list)
The lines starting with unshipped_cart.items.0 describe the API when unshipped_cart.items.0.type is 'product' or missing.
.items.0.reference Yes A public product id for this item. Example: "12-123-1234". (string or int)
.items.0.name Yes A description to include in the payment instructions. Example: "Leather Case (iPod nano) - Negro / Chocolate". (string)
.items.0.price_with_tax Yes Price with tax for one item. Example: 3030. (int)
.items.0.quantity Yes The number of items ordered by the shopper. Example: 2. (int)
.items.0.subscription_period No Subscription period of item in months. Example: 24. (positive int)
.items.0.subscription_price_per_item No Subscription cost per month per item. Example: 500. (positive int)
.items.0.subscription_price No Total subscription cost per month (subscription_price_per_item * quantity) Example: 1000. (positive int)
.items.0.subscription_vat_rate No VAT rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (positive int)
.items.0.total_with_tax Yes Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 6060. (int)
.items.0.downloadable Yes Can the buyer access or consume the product without a physical delivery? PDFs, e-tickets, software, etc are downloadable. Example: false. (true or false)
.items.0.perishable No A product is perishable if it loses its value if it is not delivered on time. Examples are fresh fruit and physical tickets. Example: false. (true or false)
.items.0.personalized No A product is personalized if it is irreversibly customized in a way that makes it less appealing to most people other than the buyer. Example: false. (true or false)
.items.0.restockable No A product is restockable if it can be sold to someone else if returned in good condition. Foodstuff is generally not restockable. Example: true. (true or false)
.items.0.category No Name of category. Will not be shown to shopper. Useful against fraud. Example: "ipod-accesorios". (string)
.items.0.description No Product description. Will not be shown to shopper. Useful against fraud. Example: "Este estuche de cuero de última moda ...". (string)
.items.0.manufacturer No Name of manufacturer. Will not be shown to shopper. Useful against fraud. Example: "Apple". (string)
.items.0.supplier No Name of supplier or provider. Will not be shown to shopper. Useful against fraud. Example: "Mayorista Makro". (string)
.items.0.product_id No Id from database. Will not be shown to shopper. Sometimes useful if 'reference' varies too much over time. Example: "6". (string or int)
.items.0.url No Product page URL in your shop. Might be shown to shopper. Useful for customer service. Example: "http://shop.example.com/ipod-accesorios/leather-case". (string)
.items.0.tracking_reference No A reference to the tracking in which this item will be handed. Example: "first". (string)
The lines starting with unshipped_cart.items.1 describe the API when unshipped_cart.items.1.type is 'handling'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.1.reference Yes A unique code that refers to this item. Does not have to exist in the shop catalogue. Example: "seur24". (string or int)
.items.1.name Yes A name to describe this item. More specific is better, i.e. prefer 'Correos' to 'Envío'. Example: "SEUR entrega en 24 horas". (string)
.items.1.total_with_tax Yes Price with tax for this handling service. Example: 242. (int)
The lines starting with unshipped_cart.items.2 describe the API when unshipped_cart.items.2.type is 'invoice_fee'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.2.total_with_tax Yes Price with tax for the invoice (i1) service. Do not use with product codes other than i1. Example: 295. (int)
The lines starting with unshipped_cart.items.3 describe the API when unshipped_cart.items.3.type is 'discount'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.3.reference Yes A unique code that refers to this discount. Can be the discount code. Example: "HALFOFF". (string or int)
.items.3.name Yes A name to describe this discount. Might be displayed in the payment instructions. Example: "50 % off the full basket!". (string)
.items.3.total_with_tax Yes Amount that this discount changes the cart value with tax. Should be negative. Example: -750. (negative int)
The lines starting with unshipped_cart.items.4 describe the API when unshipped_cart.items.4.type is 'other_payment'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.4.reference Yes A code that refers to this "other" payment. (An "other" payment means that the shopper " \ "has paid part of the cart using some other means of payment, like cash or credit card.) Example: "CASH". (string or int)
.items.4.name Yes A name to describe this payment. Example: "Paid in cash". (string)
.items.4.total_with_tax Yes Amount that this payment changes the cart value with tax. Should use opposite sign of any item it pays for. Example: -750. (int)
The lines starting with unshipped_cart.items.5 describe the API when unshipped_cart.items.5.type is 'voucher'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.5.reference Yes A code that refers to this voucher. Can be the voucher code. Example: "NoCashBack". (string or int)
.items.5.name Yes A text to describe this voucher. Might be displayed in the payment instructions. Example: "A voucher for your non-shipped items". (string)
.items.5.total_with_tax Yes Amount that this voucher changes the cart value with tax. Example: 1000. (int)
The lines starting with unshipped_cart.items.6 describe the API when unshipped_cart.items.6.type is 'service'.
.items.6.reference Yes A public id for this service. Example: "NETWORKS-ADMIN-101". (string or int)
.items.6.name Yes A name to describe this service. Might be displayed in the payment instructions. Example: "Networks Administrator Course". (string)
.items.6.ends_on Yes Maximum date for the service to be rendered or ended. Example: "2017-06-30". (ISO8601 formatted date)
.items.6.ends_in Yes Maximum time, from the start of the service, for the service to be rendered or ended. Example: "P3M15D". (ISO8601 formatted period)
.items.6.price_with_tax Yes Price with tax for one item. Example: 3030. (int)
.items.6.quantity Yes The number of items ordered by the shopper. Example: 1. (positive int)
.items.6.total_with_tax Yes Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 75020. (int)
.items.6.downloadable Yes True for services that can be fully (or sufficiently) enjoyed without a physical delivery. For instance, a course with only digital material. Example: false. (true or false)
.items.6.supplier No Name of supplier or provider. Example: "Acme Formación". (string)
.items.6.rendered No True when the service has been rendered Example: false. (true or false)
The lines starting with unshipped_cart.items.10 describe the API when unshipped_cart.items.10.type is 'subscriber_fee'.
.items.10.reference No A public product id for this item. Example: "12-123-1234". (string or int)
.items.10.name Yes A description to include in the payment instructions. Example: "Subscription fee". (string)
.items.10.price_with_tax No Price with tax for one item. Example: 3030. (int)
.items.10.quantity No The number of items ordered by the shopper. Example: 2. (positive int)
.items.10.subscription_period No Subscription period of item in months. Example: 24. (positive int)
.items.10.subscription_price_per_item No Subscription cost per month per item. Example: 500. (positive int)
.items.10.subscription_price No Total subscription cost per month (subscription_price_per_item * quantity) Example: 1000. (positive int)
.items.10.subscription_vat_rate No VAT rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (positive int)
.items.10.total_with_tax Yes Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 6060. (int)
shipped_cart Yes Fields describing the shipped items.
.currency Yes Currency code for all money amounts. Example: "EUR". (string)
.order_total_with_tax Yes Total value with tax of the items listed below. Example: 6097. (int)
.items Yes List of shipped items in the order. The list can contain zero or more instances of each item type. (list)
The lines starting with shipped_cart.items.0 describe the API when shipped_cart.items.0.type is 'product' or missing.
.items.0.reference Yes A public product id for this item. Example: "12-123-1234". (string or int)
.items.0.name Yes A description to include in the payment instructions. Example: "Leather Case (iPod nano) - Negro / Chocolate". (string)
.items.0.price_with_tax Yes Price with tax for one item. Example: 3030. (int)
.items.0.quantity Yes The number of items ordered by the shopper. Example: 2. (int)
.items.0.subscription_period No Subscription period of item in months. Example: 24. (positive int)
.items.0.subscription_price_per_item No Subscription cost per month per item. Example: 500. (positive int)
.items.0.subscription_price No Total subscription cost per month (subscription_price_per_item * quantity) Example: 1000. (positive int)
.items.0.subscription_vat_rate No VAT rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (positive int)
.items.0.total_with_tax Yes Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 6060. (int)
.items.0.downloadable Yes Can the buyer access or consume the product without a physical delivery? PDFs, e-tickets, software, etc are downloadable. Example: false. (true or false)
.items.0.perishable No A product is perishable if it loses its value if it is not delivered on time. Examples are fresh fruit and physical tickets. Example: false. (true or false)
.items.0.personalized No A product is personalized if it is irreversibly customized in a way that makes it less appealing to most people other than the buyer. Example: false. (true or false)
.items.0.restockable No A product is restockable if it can be sold to someone else if returned in good condition. Foodstuff is generally not restockable. Example: true. (true or false)
.items.0.category No Name of category. Will not be shown to shopper. Useful against fraud. Example: "ipod-accesorios". (string)
.items.0.description No Product description. Will not be shown to shopper. Useful against fraud. Example: "Este estuche de cuero de última moda ...". (string)
.items.0.manufacturer No Name of manufacturer. Will not be shown to shopper. Useful against fraud. Example: "Apple". (string)
.items.0.supplier No Name of supplier or provider. Will not be shown to shopper. Useful against fraud. Example: "Mayorista Makro". (string)
.items.0.product_id No Id from database. Will not be shown to shopper. Sometimes useful if 'reference' varies too much over time. Example: "6". (string or int)
.items.0.url No Product page URL in your shop. Might be shown to shopper. Useful for customer service. Example: "http://shop.example.com/ipod-accesorios/leather-case". (string)
.items.0.tracking_reference No A reference to the tracking in which this item will be handed. Example: "first". (string)
.items.0.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.1 describe the API when shipped_cart.items.1.type is 'handling'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.1.reference Yes A unique code that refers to this item. Does not have to exist in the shop catalogue. Example: "seur24". (string or int)
.items.1.name Yes A name to describe this item. More specific is better, i.e. prefer 'Correos' to 'Envío'. Example: "SEUR entrega en 24 horas". (string)
.items.1.total_with_tax Yes Price with tax for this handling service. Example: 242. (int)
.items.1.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.2 describe the API when shipped_cart.items.2.type is 'invoice_fee'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.2.total_with_tax Yes Price with tax for the invoice (i1) service. Do not use with product codes other than i1. Example: 295. (int)
.items.2.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.3 describe the API when shipped_cart.items.3.type is 'discount'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.3.reference Yes A unique code that refers to this discount. Can be the discount code. Example: "HALFOFF". (string or int)
.items.3.name Yes A name to describe this discount. Might be displayed in the payment instructions. Example: "50 % off the full basket!". (string)
.items.3.total_with_tax Yes Amount that this discount changes the cart value with tax. Should be negative. Example: -750. (int)
.items.3.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.4 describe the API when shipped_cart.items.4.type is 'other_payment'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.4.reference Yes A code that refers to this "other" payment. (An "other" payment means that the shopper " \ "has paid part of the cart using some other means of payment, like cash or credit card.) Example: "CASH". (string or int)
.items.4.name Yes A name to describe this payment. Example: "Paid in cash". (string)
.items.4.total_with_tax Yes Amount that this payment changes the cart value with tax. Should use opposite sign of any item it pays for. Example: -750. (int)
.items.4.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.5 describe the API when shipped_cart.items.5.type is 'voucher'.
Note that keys "quantity" and "price_with_tax" are not allowed in this section.
.items.5.reference Yes A code that refers to this voucher. Can be the voucher code. Example: "NoCashBack". (string or int)
.items.5.name Yes A text to describe this voucher. Might be displayed in the payment instructions. Example: "A voucher for your non-shipped items". (string)
.items.5.total_with_tax Yes Amount that this voucher changes the cart value with tax. Example: 1000. (int)
.items.5.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.6 describe the API when shipped_cart.items.6.type is 'service'.
.items.6.reference Yes A public id for this service. Example: "NETWORKS-ADMIN-101". (string or int)
.items.6.name Yes A name to describe this service. Might be displayed in the payment instructions. Example: "Networks Administrator Course". (string)
.items.6.ends_on Yes Maximum date for the service to be rendered or ended. Example: "2017-06-30". (ISO8601 formatted date)
.items.6.ends_in Yes Maximum time, from the start of the service, for the service to be rendered or ended. Example: "P3M15D". (ISO8601 formatted period)
.items.6.price_with_tax Yes Price with tax for one item. Example: 3030. (int)
.items.6.quantity Yes The number of items ordered by the shopper. Example: 1. (positive int)
.items.6.total_with_tax Yes Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 75020. (int)
.items.6.downloadable Yes True for services that can be fully (or sufficiently) enjoyed without a physical delivery. For instance, a course with only digital material. Example: false. (true or false)
.items.6.supplier No Name of supplier or provider. Example: "Acme Formación". (string)
.items.6.rendered No True when the service has been rendered Example: false. (true or false)
.items.6.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
The lines starting with shipped_cart.items.10 describe the API when shipped_cart.items.10.type is 'subscriber_fee'.
.items.10.reference No A public product id for this item. Example: "12-123-1234". (string or int)
.items.10.name Yes A description to include in the payment instructions. Example: "Subscription fee". (string)
.items.10.price_with_tax No Price with tax for one item. Example: 3030. (int)
.items.10.quantity No The number of items ordered by the shopper. Example: 2. (positive int)
.items.10.subscription_period No Subscription period of item in months. Example: 24. (positive int)
.items.10.subscription_price_per_item No Subscription cost per month per item. Example: 500. (positive int)
.items.10.subscription_price No Total subscription cost per month (subscription_price_per_item * quantity) Example: 1000. (positive int)
.items.10.subscription_vat_rate No VAT rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (positive int)
.items.10.total_with_tax Yes Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 6060. (int)
.items.10.shipment_ref ** A reference to the shipment that includes this item. Example: "1234-2345-45". (string)
** Mandatory for merchants using shipment-based disbursements, not permitted for others.
cancellation_reason No String containing the cancellation reason when clearing an order. Allowed values are 'change' (indicating customer wants to change the order), 'change_payment_method' (indicating customer wants to change payment method), customer_cancel' (indicating customer wants to cancel the order), 'out_of_stock' (indicating shop cannot fulfill order) and 'other'. Example: "customer_cancel". (string or null)
trackings No A list of trackings for the order.
The lines starting with trackings.0 describe the API when trackings.0.type is 'pickup_store'.
.0.reference Yes Internal tracking reference. Example: "first". (string)
.0.operator_ref No Permanent identifier for the operator that handed the delivery. Example: "123-009". (string)
.0.store_ref No Permanent identifier for the store that handled this delivery. Example: "maquinista". (string)
.0.tracking_number No Tracking number. Example: "AB331". (string)
.0.available_at No When this delivery was available in the store. Example: "2014-02-05T13:21:22+01:00". (ISO8601 formatted timestamp)
.0.delivered_at No When this delivery was handed. When set, the delivey is considered to be handed. Example: "2014-02-05T19:21:22+01:00". (ISO8601 formatted timestamp)
.0.address_line_1 No Address line 1 for the store. Example: "1600 Pennsylvania Avenue". (string)
.0.address_line_2 No Address line 2 for the store. Example: "5º". (string)
.0.postal_code No Postal code. Example: "08013". (string)
.0.city No City. Example: "Barcelona". (string)
.0.state No State or region. Example: "Barcelona". (string)
.0.country_code No Country code. Example: "ES". (ISO-3166 alpha-2/3 code)
The lines starting with trackings.1 describe the API when trackings.1.type is 'pickup_point'.
.1.reference Yes Tracking reference. Example: "second". (string)
.1.operator_ref No Permanent identifier for the operator that handed the delivery. Example: "123-009". (string)
.1.store_ref No Permanent identifier for the store that handled this delivery. Example: "maquinista". (string)
.1.tracking_number No Tracking number. Example: "AB331". (string)
.1.available_at No When this delivery was available in the store. Example: "2014-02-05T13:21:22+01:00". (ISO8601 formatted timestamp)
.1.delivered_at No When this delivery was handed. When set, the delivey is considered to be handed. Example: "2014-02-05T19:21:22+01:00". (ISO8601 formatted timestamp)
.1.address_line_1 No Address line 1 for the pickup point. Example: "1600 Pennsylvania Avenue". (string)
.1.address_line_2 No Address line 2 for the pickup point. Example: "5º". (string)
.1.postal_code No Postal code. Example: "08013". (string)
.1.city No City. Example: "Barcelona". (string)
.1.state No State or region. Example: "Barcelona". (string)
.1.country_code No Country code. Example: "ES". (ISO-3166 alpha-2/3 code)
The lines starting with trackings.2 describe the API when trackings.2.type is 'postal'.
.2.reference Yes Internal tracking reference. Example: "third". (string)
.2.carrier Yes The name of the company that handled this delivery. Example: "SEUR". (string)
.2.tracking_number No Tracking number. Example: "TX123". (string)
.2.tracking_url No Tracking URL. Example: "https://logistics.es/TX123". (an HTTPS URL string)
.2.delivered_at No When this delivery was handed. When set, the delivey is considered to be handed. Example: "2014-02-05T19:21:22+01:00". (ISO8601 formatted timestamp)
delivery_method No Delivery method used on the purchase.
.name Yes Name of the delivery method. Example: "SEUR24". (string)
.days No Days it takes to deliver the goods. Example: "¡Entrega día siguiente!". (string)
.provider No Company or agent that performs the delivery. Example: "Correos". (string)
.home_delivery No If goods are delivered to the buyer's home or office and not to a pick-up place. Example: true. (true or false)
delivery_address No Fields describing the delivery address.
.given_names Yes Shopper's given names for delivery. Example: "Maria José". (string)
.surnames Yes Shopper's last names for delivery. Example: "Barroso Rajoy". (string)
.company Yes Shopper company name. (string)
.address_line_1 Yes Delivery address line 1. Example: "C/ Aragó 383". (string)
.address_line_2 Yes Delivery address line 2. Example: "5º". (string)
.postal_code Yes Delivery address address postal code. Example: "08013". (string)
.city Yes Delivery address city. Example: "Barcelona". (string)
.country_code Yes Delivery address country code. Example: "ES". (string)
.phone No Shopper phone. Can be a mobile phone. Example: "933 033 033". (string)
.mobile_phone No Shopper mobile phone. Only use this field if the shopper indicated that this number is a mobile phone. Example: "615 615 615". (string)
.state No Shopper region or state. Example: "Barcelona". (string)
.extra No Extra handling information that the shopper adds to the order. Example: "I'm home between 9 and 12.". (string)
.vat_number No Shopper VAT number. Example: "B12345". (string)
invoice_address No Fields describing the invoice address.
.given_names Yes Shopper's given names for invoice. Example: "Maria José". (string)
.surnames Yes Shopper's last names for invoice. Example: "Barroso Rajoy". (string)
.company Yes Shopper company name. (string)
.address_line_1 Yes Invoice address line 1. (string)
.address_line_2 Yes Invoice address line 2. (string)
.postal_code Yes Invoice address address postal code. (string)
.city Yes Invoice address city. (string)
.country_code Yes Invoice address country code. Example: "ES". (string)
.phone No Shopper phone. Can be a mobile phone. Example: "933 033 033". (string)
.mobile_phone No Shopper mobile phone. Only use this field if the shopper indicated that this number is a mobile phone. Example: "615 615 615". (string)
.state No Shopper region or state. Example: "Tarragona". (string)
.extra No Extra handling information that the shopper adds to the order. Example: "I'm home between 9 and 12.". (string)
.vat_number No Shopper VAT number. Example: "B12345". (string)
customer No Fields describing the customer.
.given_names Yes Customer given names. Example: "Maria José". (string)
.surnames Yes Customer surnames. Example: "Barroso Rajoy". (string)
.title No Customer title and/or gender. Use the one of 'mr', 'ms', 'mrs', 'miss' or 'mx' that is closest to the information supplied by the customer. If none of these can be inferred, use the title that the customer entered as-is. See also 'Note about title' in the docs. Example: "mr". (string)
.email Yes Customer email. Example: "nisse@example.com". (string)
.ref No Customer reference number in the shop's database. Example: 123. (string or int)
.date_of_birth No Customer date of birth in ISO-8601 format. Example: "1980-01-20". (string)
.nin No Customer's national identity number. For Spanish DNI, please include final letter. Example: "13003009L". (string)
.company No Customer company name. (string)
.vat_number No Shopper VAT number. Example: "B12345". (string)
.rating No The merchant's rating of this customer. 0 to 100, inclusive, where 0 is "cannot be trusted" and 100 is "very trustworthy". Example: 100. (int)
.nin_control No A validation code printed in the physical DNI or NIE. Required for multistore merchants and physical stores. See the FAQs to know more. Example: "15012018F2". (string)
.vehicle ** Fields describing the customer's vehicle
.vehicle.plaque Yes Plaque identificator from customer's vehicle Example: "0000AAA". (string)
.vehicle.brand No Brand from customer's vehicle Example: "Volkswagen". (string)
.vehicle.model No Model from customer's vehicle Example: "Beetle". (string)
.vehicle.frame No Frame identificator from customer's vehicle Example: "VF1RFD00653635032". (string)
.vehicle.first_registration_date No First registration date plaque from customer's vehicle Example: "2000-03-25". (string)
platform Yes Fields describing the store backend platform. These are valuable for when diagnosing unexpected behaviour.
.name Yes Name of the backend platform. If it is a "standard" platform with customisations, use 'Openbravo/theshop.es', 'SAP/theshop.es' or similar. If it is a custom platform, use 'custom'. Example: "Navision/www.theshop.es". (string)
.version Yes Version of the platform. If you don't use explicit versioning, use a release date instead. Example: "1.1". (string)
.plugin_version No Version of the plugin or platform module. If you don't use explicit versioning, use a release date instead. Example: "1.0.2". (string)
.uname Yes uname of the shop server. In PHP, use php_uname(). Example: "Darwin roatan.local 13.0.0 Darwin Kernel Version 13.0... x86_64". (string)
.db_name No DB used. Example: "MSSQL". (string)
.db_version No Version of the DB. Example: "1.2.3". (string)
subscription No Fields describing the subscription.
.period_extension No Number of weeks to extend the subscription period. Example: 12. (positive int)

JSON examples

Some integrations use specific features that depend on the contract between the merchant and SeQura. Use the checkboxes below to see a custom example. You can ask your SeQura’s integration buddy about the contract options that affect your integration.

Contract options

  • Services: The shop sells a service, i.e., it has an ending date (ends_in or ends_on fields) for the service. F.i, a course.
  • Multistore: The shop has a physical store. It may have one or many different stores. This option requires these addtional fields: store_ref, operator_ref and nin_control.
  • Garage: Garages have to inform the vehicle's plaque. They are also multistore. The shop requires to add garage_chain field in case it belongs to an specific chain
  • Shipment_ref: If your shop makes partial shipments and it wants to track them at disbursement, use this option. Read more.

Generate the payload for your contract options

PHP example

This example includes all options and features available.

$order = array();
$order["merchant"] = array();
$order["merchant"]["id"] = "s1";
// $order["merchant"]["store_ref"] = "maquinista"; // Mandatory for multistore merchants and physical stores, not permitted for others.
$order["merchant_reference"] = array();
$order["merchant_reference"]["order_ref_1"] = "ZXCV1234";
$order["merchant_reference"]["order_ref_2"] = "0080-1234-4343-5353"; // optional
$order["unshipped_cart"] = array();
$order["unshipped_cart"]["currency"] = "EUR";
$order["unshipped_cart"]["order_total_with_tax"] = 6097;
$order["unshipped_cart"]["items"] = array();
$order["unshipped_cart"]["items"][0] = array();
$order["unshipped_cart"]["items"][0]["reference"] = "12-123-1234";
$order["unshipped_cart"]["items"][0]["name"] = "Leather Case (iPod nano) - Negro / Chocolate";
$order["unshipped_cart"]["items"][0]["price_with_tax"] = 3030;
$order["unshipped_cart"]["items"][0]["quantity"] = 2;
$order["unshipped_cart"]["items"][0]["subscription_period"] = 24; // optional
$order["unshipped_cart"]["items"][0]["subscription_price_per_item"] = 500; // optional
$order["unshipped_cart"]["items"][0]["subscription_price"] = 1000; // optional
$order["unshipped_cart"]["items"][0]["subscription_vat_rate"] = 2100; // optional
$order["unshipped_cart"]["items"][0]["total_with_tax"] = 6060;
$order["unshipped_cart"]["items"][0]["downloadable"] = false;
$order["unshipped_cart"]["items"][0]["perishable"] = false; // optional
$order["unshipped_cart"]["items"][0]["personalized"] = false; // optional
$order["unshipped_cart"]["items"][0]["restockable"] = true; // optional
$order["unshipped_cart"]["items"][0]["category"] = "ipod-accesorios"; // optional
$order["unshipped_cart"]["items"][0]["description"] = "Este estuche de cuero de última moda ..."; // optional
$order["unshipped_cart"]["items"][0]["manufacturer"] = "Apple"; // optional
$order["unshipped_cart"]["items"][0]["supplier"] = "Mayorista Makro"; // optional
$order["unshipped_cart"]["items"][0]["product_id"] = "6"; // optional
$order["unshipped_cart"]["items"][0]["url"] = "http://shop.example.com/ipod-accesorios/leather-case"; // optional
$order["unshipped_cart"]["items"][0]["tracking_reference"] = "first"; // optional
$order["unshipped_cart"]["items"][1] = array();
$order["unshipped_cart"]["items"][1]["type"] = "handling";
$order["unshipped_cart"]["items"][1]["reference"] = "seur24";
$order["unshipped_cart"]["items"][1]["name"] = "SEUR entrega en 24 horas";
$order["unshipped_cart"]["items"][1]["total_with_tax"] = 242;
$order["unshipped_cart"]["items"][2] = array();
$order["unshipped_cart"]["items"][2]["type"] = "invoice_fee";
$order["unshipped_cart"]["items"][2]["total_with_tax"] = 295;
$order["unshipped_cart"]["items"][3] = array();
$order["unshipped_cart"]["items"][3]["type"] = "discount";
$order["unshipped_cart"]["items"][3]["reference"] = "HALFOFF";
$order["unshipped_cart"]["items"][3]["name"] = "50 % off the full basket!";
$order["unshipped_cart"]["items"][3]["total_with_tax"] = -750;
$order["unshipped_cart"]["items"][4] = array();
$order["unshipped_cart"]["items"][4]["type"] = "other_payment";
$order["unshipped_cart"]["items"][4]["reference"] = "CASH";
$order["unshipped_cart"]["items"][4]["name"] = "Paid in cash";
$order["unshipped_cart"]["items"][4]["total_with_tax"] = -750;
$order["unshipped_cart"]["items"][5] = array();
$order["unshipped_cart"]["items"][5]["type"] = "voucher";
$order["unshipped_cart"]["items"][5]["reference"] = "NoCashBack";
$order["unshipped_cart"]["items"][5]["name"] = "A voucher for your non-shipped items";
$order["unshipped_cart"]["items"][5]["total_with_tax"] = 1000;
$order["unshipped_cart"]["items"][6] = array();
$order["unshipped_cart"]["items"][6]["type"] = "service";
$order["unshipped_cart"]["items"][6]["reference"] = "NETWORKS-ADMIN-101";
$order["unshipped_cart"]["items"][6]["name"] = "Networks Administrator Course";
$order["unshipped_cart"]["items"][6]["ends_in"] = "P3M15D";
$order["unshipped_cart"]["items"][6]["price_with_tax"] = 3030;
$order["unshipped_cart"]["items"][6]["quantity"] = 1;
$order["unshipped_cart"]["items"][6]["total_with_tax"] = 75020;
$order["unshipped_cart"]["items"][6]["downloadable"] = false;
$order["unshipped_cart"]["items"][6]["supplier"] = "Acme Formación"; // optional
$order["unshipped_cart"]["items"][6]["rendered"] = false; // optional
$order["unshipped_cart"]["items"][10] = array();
$order["unshipped_cart"]["items"][10]["type"] = "subscriber_fee";
$order["unshipped_cart"]["items"][10]["reference"] = "12-123-1234"; // optional
$order["unshipped_cart"]["items"][10]["name"] = "Subscription fee";
$order["unshipped_cart"]["items"][10]["price_with_tax"] = 3030; // optional
$order["unshipped_cart"]["items"][10]["quantity"] = 2; // optional
$order["unshipped_cart"]["items"][10]["subscription_period"] = 24; // optional
$order["unshipped_cart"]["items"][10]["subscription_price_per_item"] = 500; // optional
$order["unshipped_cart"]["items"][10]["subscription_price"] = 1000; // optional
$order["unshipped_cart"]["items"][10]["subscription_vat_rate"] = 2100; // optional
$order["unshipped_cart"]["items"][10]["total_with_tax"] = 6060;
$order["shipped_cart"] = array();
$order["shipped_cart"]["currency"] = "EUR";
$order["shipped_cart"]["order_total_with_tax"] = 6097;
$order["shipped_cart"]["items"] = array();
$order["shipped_cart"]["items"][0] = array();
$order["shipped_cart"]["items"][0]["reference"] = "12-123-1234";
$order["shipped_cart"]["items"][0]["name"] = "Leather Case (iPod nano) - Negro / Chocolate";
$order["shipped_cart"]["items"][0]["price_with_tax"] = 3030;
$order["shipped_cart"]["items"][0]["quantity"] = 2;
$order["shipped_cart"]["items"][0]["subscription_period"] = 24; // optional
$order["shipped_cart"]["items"][0]["subscription_price_per_item"] = 500; // optional
$order["shipped_cart"]["items"][0]["subscription_price"] = 1000; // optional
$order["shipped_cart"]["items"][0]["subscription_vat_rate"] = 2100; // optional
$order["shipped_cart"]["items"][0]["total_with_tax"] = 6060;
$order["shipped_cart"]["items"][0]["downloadable"] = false;
$order["shipped_cart"]["items"][0]["perishable"] = false; // optional
$order["shipped_cart"]["items"][0]["personalized"] = false; // optional
$order["shipped_cart"]["items"][0]["restockable"] = true; // optional
$order["shipped_cart"]["items"][0]["category"] = "ipod-accesorios"; // optional
$order["shipped_cart"]["items"][0]["description"] = "Este estuche de cuero de última moda ..."; // optional
$order["shipped_cart"]["items"][0]["manufacturer"] = "Apple"; // optional
$order["shipped_cart"]["items"][0]["supplier"] = "Mayorista Makro"; // optional
$order["shipped_cart"]["items"][0]["product_id"] = "6"; // optional
$order["shipped_cart"]["items"][0]["url"] = "http://shop.example.com/ipod-accesorios/leather-case"; // optional
$order["shipped_cart"]["items"][0]["tracking_reference"] = "first"; // optional
// $order["shipped_cart"]["items"][0]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][1] = array();
$order["shipped_cart"]["items"][1]["type"] = "handling";
$order["shipped_cart"]["items"][1]["reference"] = "seur24";
$order["shipped_cart"]["items"][1]["name"] = "SEUR entrega en 24 horas";
$order["shipped_cart"]["items"][1]["total_with_tax"] = 242;
// $order["shipped_cart"]["items"][1]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][2] = array();
$order["shipped_cart"]["items"][2]["type"] = "invoice_fee";
$order["shipped_cart"]["items"][2]["total_with_tax"] = 295;
// $order["shipped_cart"]["items"][2]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][3] = array();
$order["shipped_cart"]["items"][3]["type"] = "discount";
$order["shipped_cart"]["items"][3]["reference"] = "HALFOFF";
$order["shipped_cart"]["items"][3]["name"] = "50 % off the full basket!";
$order["shipped_cart"]["items"][3]["total_with_tax"] = -750;
// $order["shipped_cart"]["items"][3]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][4] = array();
$order["shipped_cart"]["items"][4]["type"] = "other_payment";
$order["shipped_cart"]["items"][4]["reference"] = "CASH";
$order["shipped_cart"]["items"][4]["name"] = "Paid in cash";
$order["shipped_cart"]["items"][4]["total_with_tax"] = -750;
// $order["shipped_cart"]["items"][4]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][5] = array();
$order["shipped_cart"]["items"][5]["type"] = "voucher";
$order["shipped_cart"]["items"][5]["reference"] = "NoCashBack";
$order["shipped_cart"]["items"][5]["name"] = "A voucher for your non-shipped items";
$order["shipped_cart"]["items"][5]["total_with_tax"] = 1000;
// $order["shipped_cart"]["items"][5]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][6] = array();
$order["shipped_cart"]["items"][6]["type"] = "service";
$order["shipped_cart"]["items"][6]["reference"] = "NETWORKS-ADMIN-101";
$order["shipped_cart"]["items"][6]["name"] = "Networks Administrator Course";
$order["shipped_cart"]["items"][6]["ends_in"] = "P3M15D";
$order["shipped_cart"]["items"][6]["price_with_tax"] = 3030;
$order["shipped_cart"]["items"][6]["quantity"] = 1;
$order["shipped_cart"]["items"][6]["total_with_tax"] = 75020;
$order["shipped_cart"]["items"][6]["downloadable"] = false;
$order["shipped_cart"]["items"][6]["supplier"] = "Acme Formación"; // optional
$order["shipped_cart"]["items"][6]["rendered"] = false; // optional
// $order["shipped_cart"]["items"][6]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["shipped_cart"]["items"][10] = array();
$order["shipped_cart"]["items"][10]["type"] = "subscriber_fee";
$order["shipped_cart"]["items"][10]["reference"] = "12-123-1234"; // optional
$order["shipped_cart"]["items"][10]["name"] = "Subscription fee";
$order["shipped_cart"]["items"][10]["price_with_tax"] = 3030; // optional
$order["shipped_cart"]["items"][10]["quantity"] = 2; // optional
$order["shipped_cart"]["items"][10]["subscription_period"] = 24; // optional
$order["shipped_cart"]["items"][10]["subscription_price_per_item"] = 500; // optional
$order["shipped_cart"]["items"][10]["subscription_price"] = 1000; // optional
$order["shipped_cart"]["items"][10]["subscription_vat_rate"] = 2100; // optional
$order["shipped_cart"]["items"][10]["total_with_tax"] = 6060;
// $order["shipped_cart"]["items"][10]["shipment_ref"] = "1234-2345-45"; // Mandatory for merchants using shipment-based disbursements, not permitted for others.
$order["cancellation_reason"] = "customer_cancel"; // optional
$order["trackings"] = array(); // optional
$order["trackings"][0] = array();
$order["trackings"][0]["type"] = "pickup_store";
$order["trackings"][0]["reference"] = "first";
$order["trackings"][0]["operator_ref"] = "123-009"; // optional
$order["trackings"][0]["store_ref"] = "maquinista"; // optional
$order["trackings"][0]["tracking_number"] = "AB331"; // optional
$order["trackings"][0]["available_at"] = "2014-02-05T13:21:22+01:00"; // optional
$order["trackings"][0]["delivered_at"] = "2014-02-05T19:21:22+01:00"; // optional
$order["trackings"][0]["address_line_1"] = "1600 Pennsylvania Avenue"; // optional
$order["trackings"][0]["address_line_2"] = "5º"; // optional
$order["trackings"][0]["postal_code"] = "08013"; // optional
$order["trackings"][0]["city"] = "Barcelona"; // optional
$order["trackings"][0]["state"] = "Barcelona"; // optional
$order["trackings"][0]["country_code"] = "ES"; // optional
$order["trackings"][1] = array();
$order["trackings"][1]["type"] = "pickup_point";
$order["trackings"][1]["reference"] = "second";
$order["trackings"][1]["operator_ref"] = "123-009"; // optional
$order["trackings"][1]["store_ref"] = "maquinista"; // optional
$order["trackings"][1]["tracking_number"] = "AB331"; // optional
$order["trackings"][1]["available_at"] = "2014-02-05T13:21:22+01:00"; // optional
$order["trackings"][1]["delivered_at"] = "2014-02-05T19:21:22+01:00"; // optional
$order["trackings"][1]["address_line_1"] = "1600 Pennsylvania Avenue"; // optional
$order["trackings"][1]["address_line_2"] = "5º"; // optional
$order["trackings"][1]["postal_code"] = "08013"; // optional
$order["trackings"][1]["city"] = "Barcelona"; // optional
$order["trackings"][1]["state"] = "Barcelona"; // optional
$order["trackings"][1]["country_code"] = "ES"; // optional
$order["trackings"][2] = array();
$order["trackings"][2]["type"] = "postal";
$order["trackings"][2]["reference"] = "third";
$order["trackings"][2]["carrier"] = "SEUR";
$order["trackings"][2]["tracking_number"] = "TX123"; // optional
$order["trackings"][2]["tracking_url"] = "https://logistics.es/TX123"; // optional
$order["trackings"][2]["delivered_at"] = "2014-02-05T19:21:22+01:00"; // optional
$order["delivery_method"] = array(); // optional
$order["delivery_method"]["name"] = "SEUR24";
$order["delivery_method"]["days"] = "¡Entrega día siguiente!"; // optional
$order["delivery_method"]["provider"] = "Correos"; // optional
$order["delivery_method"]["home_delivery"] = true; // optional
$order["delivery_address"] = array(); // optional
$order["delivery_address"]["given_names"] = "Maria José";
$order["delivery_address"]["surnames"] = "Barroso Rajoy";
$order["delivery_address"]["company"] = "";
$order["delivery_address"]["address_line_1"] = "C/ Aragó 383";
$order["delivery_address"]["address_line_2"] = "5º";
$order["delivery_address"]["postal_code"] = "08013";
$order["delivery_address"]["city"] = "Barcelona";
$order["delivery_address"]["country_code"] = "ES";
$order["delivery_address"]["phone"] = "933 033 033"; // optional
$order["delivery_address"]["mobile_phone"] = "615 615 615"; // optional
$order["delivery_address"]["state"] = "Barcelona"; // optional
$order["delivery_address"]["extra"] = "I'm home between 9 and 12."; // optional
$order["delivery_address"]["vat_number"] = "B12345"; // optional
$order["invoice_address"] = array(); // optional
$order["invoice_address"]["given_names"] = "Maria José";
$order["invoice_address"]["surnames"] = "Barroso Rajoy";
$order["invoice_address"]["company"] = "";
$order["invoice_address"]["address_line_1"] = "";
$order["invoice_address"]["address_line_2"] = "";
$order["invoice_address"]["postal_code"] = "";
$order["invoice_address"]["city"] = "";
$order["invoice_address"]["country_code"] = "ES";
$order["invoice_address"]["phone"] = "933 033 033"; // optional
$order["invoice_address"]["mobile_phone"] = "615 615 615"; // optional
$order["invoice_address"]["state"] = "Tarragona"; // optional
$order["invoice_address"]["extra"] = "I'm home between 9 and 12."; // optional
$order["invoice_address"]["vat_number"] = "B12345"; // optional
$order["customer"] = array(); // optional
$order["customer"]["given_names"] = "Maria José";
$order["customer"]["surnames"] = "Barroso Rajoy";
$order["customer"]["title"] = "mr"; // optional
$order["customer"]["email"] = "nisse@example.com";
$order["customer"]["ref"] = 123; // optional
$order["customer"]["date_of_birth"] = "1980-01-20"; // optional
$order["customer"]["nin"] = "13003009L"; // optional
$order["customer"]["company"] = ""; // optional
$order["customer"]["vat_number"] = "B12345"; // optional
$order["customer"]["rating"] = 100; // optional
$order["customer"]["nin_control"] = "15012018F2"; // optional
// $order["customer"]["vehicle"] = array(); // contract
$order["customer"]["vehicle"]["plaque"] = "0000AAA";
$order["customer"]["vehicle"]["brand"] = "Volkswagen"; // optional
$order["customer"]["vehicle"]["model"] = "Beetle"; // optional
$order["customer"]["vehicle"]["frame"] = "VF1RFD00653635032"; // optional
$order["customer"]["vehicle"]["first_registration_date"] = "2000-03-25"; // optional
$order["platform"] = array();
$order["platform"]["name"] = "Navision/www.theshop.es";
$order["platform"]["version"] = "1.1";
$order["platform"]["plugin_version"] = "1.0.2"; // optional
$order["platform"]["uname"] = "Darwin roatan.local 13.0.0 Darwin Kernel Version 13.0... x86_64";
$order["platform"]["db_name"] = "MSSQL"; // optional
$order["platform"]["db_version"] = "1.2.3"; // optional
$order["subscription"] = array(); // optional
$order["subscription"]["period_extension"] = 12; // optional