Skip to main content
POST
/
v1
/
orders
curl --request POST \
  --url https://{cluster}.voucherify.io/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '{
  "amount": 20000,
  "customer": {
    "source_id": "sample_customer"
  },
  "status": "PAID",
  "items": [
    {
      "quantity": 1,
      "price": 20000,
      "source_id": "sample product1",
      "related_object": "product",
      "product": {
        "metadata": {
          "key": "value"
        }
      }
    }
  ]
}'
{
  "id": "ord_cRKOEXiBOj0EZKF7g9n6l0eH",
  "source_id": "new",
  "created_at": "2022-09-09T09:20:01.660Z",
  "updated_at": "2022-09-09T09:24:43.604Z",
  "status": "FULFILLED",
  "amount": 121700,
  "total_amount": 121700,
  "items": [
    {
      "object": "order_item",
      "source_id": "prod_1",
      "related_object": "product",
      "quantity": 2,
      "amount": 120000,
      "price": 60000,
      "subtotal_amount": 120000,
      "product": {
        "id": "prod_0b7d7c4e814be5c502",
        "source_id": "prod_1",
        "name": "Apple iPhone 12",
        "metadata": {
          "color": [
            "purple"
          ],
          "vendor": "mall"
        },
        "price": 60000
      }
    },
    {
      "object": "order_item",
      "source_id": "ComicBook_1",
      "related_object": "sku",
      "product_id": "prod_0b7d7dfb05cbe5c616",
      "quantity": 1,
      "amount": 1700,
      "price": 1700,
      "subtotal_amount": 1700,
      "product": {
        "id": "prod_0b7d7dfb05cbe5c616",
        "source_id": "Books",
        "name": "Comic Books1",
        "metadata": {
          "color": [
            "silver"
          ],
          "vendor": "Bookstore1"
        },
        "price": 2100
      },
      "sku": {
        "id": "sku_0b7d7dfb090be5c619",
        "source_id": "ComicBook_1",
        "sku": "Comics1",
        "metadata": {
          "color": [
            "golden"
          ],
          "vendor": "islands"
        },
        "price": 1700
      }
    }
  ],
  "metadata": {
    "location_id": [
      "L1",
      "L2"
    ],
    "payment_mean": [
      "paypal",
      "credit-card"
    ]
  },
  "customer": {
    "id": "cust_H0nXrItO1DNV3UiPIl54HA5o",
    "object": "customer"
  },
  "referrer": {
    "id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv",
    "object": "customer"
  },
  "customer_id": "cust_H0nXrItO1DNV3UiPIl54HA5o",
  "referrer_id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv",
  "object": "order"
}

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

Specify the order parameters.

Request body schema for POST v1/orders. Order information.

​
created_at
string<date-time>

Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

​
referrer_id
string | null

Unique referrer ID.

Example:

"cust_nM4jqPiaXUvQdVSA6vTRUnix"

​
customer
object
​
referrer
object
​
id
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.

​
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.

Response

200 - application/json

Returns an order object if the operation succeeded.

Response body schema for POST v1/orders. Order information.

​
id
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

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

​
initial_amount
integer

This is the sum of the order items' amounts before any discount or other effect (e.g. add missing units) is applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

​
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_discount_amount
integer

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

​
total_discount_amount
integer

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

​
total_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

​
applied_discount_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).

​
items_applied_discount_amount
integer

Sum of all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
sum(items, i => i.applied_discount_amount)

​
total_applied_discount_amount
integer

Sum of all order-level AND all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00).
total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount

​
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.

​
object
enum<string>
default:order

The type of the object represented by JSON.

Available options:
order
​
created_at
string<date-time>

Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

​
updated_at
string<date-time> | null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example:

"2021-12-22T10:14:45.316Z"

​
customer_id
string | null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

​
referrer_id
string | null

Unique referrer ID.

Example:

"cust_nM4jqPiaXUvQdVSA6vTRUnix"

​
customer
object
​
referrer
object
​
redemptions
object
​
items
Order Item Calculated · object[]

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

⌘I