Import Orders

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/orders/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
[
  {
    "id": "<string>",
    "source_id": "<string>",
    "status": "CREATED",
    "amount": 123,
    "initial_amount": 123,
    "discount_amount": 123,
    "items": [
      {
        "sku_id": "<string>",
        "product_id": "<string>",
        "related_object": "product",
        "source_id": "<string>",
        "quantity": 123,
        "discount_quantity": 123,
        "initial_quantity": 123,
        "amount": 123,
        "discount_amount": 123,
        "initial_amount": 123,
        "price": 123,
        "product": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "name": "<string>",
          "metadata": {},
          "price": 123
        },
        "sku": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "sku": "<string>",
          "price": 123,
          "metadata": {}
        },
        "metadata": {}
      }
    ],
    "metadata": {},
    "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
    "customer": {
      "id": "<string>",
      "source_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "birthday": "2023-12-25",
      "birthdate": "2023-12-25",
      "address": {
        "city": "<string>",
        "state": "<string>",
        "line_1": "<string>",
        "line_2": "<string>",
        "country": "<string>",
        "postal_code": "<string>"
      },
      "metadata": {}
    },
    "referrer": {
      "id": "<string>",
      "source_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "birthday": "2023-12-25",
      "birthdate": "2023-12-25",
      "address": {
        "city": "<string>",
        "state": "<string>",
        "line_1": "<string>",
        "line_2": "<string>",
        "country": "<string>",
        "postal_code": "<string>"
      },
      "metadata": {}
    }
  }
]
'

{
  "async_action_id": "aa_0a875d56c805df6601"
}

Import Orders

🚧 Historical orders

This endpoint should only be used to import historical orders into Voucherify. For on-going synchronization, the update order endpoint should be used. This is critical because this endpoint does not store events or launch distributions. The orders will also have a created_at date that’s assigned when they’ve been imported to Voucherify. To keep track of the actual order creation date, add an order metadata in ISO 8601 date or date time format to each imported order.

Limitations

Import volume

There can be only a single on-going order import per tenant per project at a given time. The user can schedule more imports but those extra imports will be scheduled to run in sequence one by one.

Maximum count of orders in single import

There is a 2000 limit of orders per one request.

Notifications

There are no notifications on the Dashboard because this import is launched via the API.

Triggered actions

If you import orders with customers, then a logic will be scheduled responsible for placing these customers into segments and refreshing the segment’s summary. Consequently, this update will trigger

Customers entering into segments
Distributions based on any rules tied to customer entering segment(s)
Earning rules based on the customer entering segment(s)

What is not triggered

No webhooks are triggered during the import of orders - for both orders and upserted products / SKUs.
Distributions based on Order Update, Order Paid, Order Created and Order Cancelled. In other words if you have a distribution based on Order Paid and you import an order with a PAID status, the distribution is not going to be triggered.
No events are created during the import of orders - for both orders and upserted products / SKUs. In other words you won’t see any events in the Activity tab in the Dashboard such as Order created or Order paid. If you are additionally upserting products / SKUs, then you won’t see the Product created events listed, etc.
Earning rules based on Order Paid won’t be triggered.

This API request starts a process that affects Voucherify data in bulk.

In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the IN_PROGRESS status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window.

The result will return the async ID. You can verify the status of your request with GET Async Action endpoint.

POST

orders

import

Import Orders

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/orders/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
[
  {
    "id": "<string>",
    "source_id": "<string>",
    "status": "CREATED",
    "amount": 123,
    "initial_amount": 123,
    "discount_amount": 123,
    "items": [
      {
        "sku_id": "<string>",
        "product_id": "<string>",
        "related_object": "product",
        "source_id": "<string>",
        "quantity": 123,
        "discount_quantity": 123,
        "initial_quantity": 123,
        "amount": 123,
        "discount_amount": 123,
        "initial_amount": 123,
        "price": 123,
        "product": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "name": "<string>",
          "metadata": {},
          "price": 123
        },
        "sku": {
          "id": "<string>",
          "source_id": "<string>",
          "override": true,
          "sku": "<string>",
          "price": 123,
          "metadata": {}
        },
        "metadata": {}
      }
    ],
    "metadata": {},
    "referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
    "customer": {
      "id": "<string>",
      "source_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "birthday": "2023-12-25",
      "birthdate": "2023-12-25",
      "address": {
        "city": "<string>",
        "state": "<string>",
        "line_1": "<string>",
        "line_2": "<string>",
        "country": "<string>",
        "postal_code": "<string>"
      },
      "metadata": {}
    },
    "referrer": {
      "id": "<string>",
      "source_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "birthday": "2023-12-25",
      "birthdate": "2023-12-25",
      "address": {
        "city": "<string>",
        "state": "<string>",
        "line_1": "<string>",
        "line_2": "<string>",
        "country": "<string>",
        "postal_code": "<string>"
      },
      "metadata": {}
    }
  }
]
'

{
  "async_action_id": "aa_0a875d56c805df6601"
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

The request body is sent in the form of an array of order objects.

string

Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.

source_id

string | null

Unique source ID of an existing order that will be linked to the redemption of this request.

status

enum<string>

The order status.

Available options:

CREATED,

PAID,

CANCELED,

FULFILLED

amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

initial_amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

discount_amount

integer

Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

items

Order Item · object[]

Array of items applied to the order. It can include up to 500 items.

Show child attributes

items.sku_id

string

Unique identifier of the SKU. It is assigned by Voucherify.

items.product_id

string

Unique identifier of the product. It is assigned by Voucherify.

Used along with the source_id property, can be set to either sku or product.

Available options:

product,

sku

items.source_id

string

The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service.

items.quantity

integer

The quantity of the particular item in the cart.

items.discount_quantity

integer

Number of dicounted items.

items.initial_quantity

integer

A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity.

items.amount

integer

The total amount of the order item (price * quantity).

items.discount_amount

integer

Sum of all order-item-level discounts applied to the order.

items.initial_amount

integer

A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts.

items.price

integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

items.product

object

An object containing details of the related product.

Show child attributes

items.product.id

string

A unique identifier that represents the product and is assigned by Voucherify.

items.product.source_id

string

The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.

items.product.override

boolean

The override set to true is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. Override works only for endpoints that create an order in the database.

items.product.name

string

Product name.

items.product.metadata

object

A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.

items.product.price

number

Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

items.sku

object

An object containing details of the related SKU.

Show child attributes

items.sku.id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

items.sku.source_id

string

The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service.

items.sku.override

boolean

items.sku.sku

string

The SKU name.

items.sku.price

number

SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00).

items.sku.metadata

object

A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to create product collections.

items.metadata

object

metadata

object

A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas.

referrer_id

string | null

Unique referrer ID.

Example:

"cust_nM4jqPiaXUvQdVSA6vTRUnix"

customer

Customer · object

Show child attributes

customer.id

string

The ID of an existing customer.

customer.source_id

string

A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored.

customer.name

string

Customer's first and last name.

customer.description

string

An arbitrary string that you can attach to a customer object.

customer.email

string

Customer's email address.

customer.phone

string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

customer.birthday

string<date>

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

customer.birthdate

string<date>

Customer's birthdate; format YYYY-MM-DD.

customer.address

object

Customer's address.

Show child attributes

customer.address.city

string

City

customer.address.state

string

State

customer.address.line_1

string

First line of address.

customer.address.line_2

string

Second line of address.

customer.address.country

string

Country.

customer.address.postal_code

string

Postal code.

customer.metadata

object

A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments.

referrer

Referrer · object

Show child attributes

referrer.id

string

The ID of an existing customer.

referrer.source_id

string

referrer.name

string

Customer's first and last name.

referrer.description

string

An arbitrary string that you can attach to a customer object.

referrer.email

string

Customer's email address.

referrer.phone

string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

referrer.birthday

string<date>

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

referrer.birthdate

string<date>

Customer's birthdate; format YYYY-MM-DD.

referrer.address

object

Customer's address.

Show child attributes

referrer.address.city

string

City

referrer.address.state

string

State

referrer.address.line_1

string

First line of address.

referrer.address.line_2

string

Second line of address.

referrer.address.country

string

Country.

referrer.address.postal_code

string

Postal code.

referrer.metadata

object

Response

Returns the ID of the scheduled asynchronous action, informing you that your request has been accepted and the order(s) will be added to the repository asynchronously. To check the status and result, copy the async_action_id from the response and pass it using Get Async Action endpoint.

Response body schema for POST v1/orders/import. Response to requests that are processed asynchronously.

async_action_id

string

required

The ID of the scheduled asynchronous action.

Example:

"aa_0a875d56c805df6601"

Last modified on December 3, 2025

Update Order Create Orders Export

⌘I

Introduction

Endpoints

Events

Import Orders

Limitations

Import volume

Maximum count of orders in single import

Notifications

Triggered actions

What is not triggered

Authorizations

Body

Response