---
title: "Create an Order"
source_url: https://docs.rapyd.net/en/create-an-order.html
lang: en
---

# Create an Order

Create an order for goods.

For services, see [Create Subscription](https://docs.rapyd.net/en/create-subscription.md "Create Subscription").

The payment method used in the process is the customer’s default payment method. See [Pay an Order](https://docs.rapyd.net/en/pay-an-order.md "Pay an Order").

This method triggers the **Order Created** webhook. This webhook contains the same information as the response.

> **Note:**
>
> - The code samples include successful requests (200) and bad requests (400).
>
>   - For error messages that appear due to bad requests (400), see:
>
>     - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors")
>     - [Order Errors](https://docs.rapyd.net/en/order-errors.md "Order Errors")
>   - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors").

### Parameters

### Request Header Parameters

- - access_key
  - Unique access key provided by Rapyd for each authorized user.

    See [Developers](https://docs.rapyd.net/en/developers.md "Developers").
- - Content-Type
  - Indicates that the data appears in JSON format. Set to **application/json**.
- - idempotency
  - A unique key that prevents the platform from creating the same object twice.

    See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency").
- - salt
  - Random string. Recommended length: 8-16 characters.
- - signature
  - Signature calculated for each request individually.

    See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures").
- - timestamp
  - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds).

### Request Body Parameters

- - coupon
  - ID of a coupon that is applied against this order. String starting with **coupon_**. The `duration` field of the coupon must be set to **repeating**, and the `duration_in_months` and `discount_duration_in_uses` fields must be set to **1**.
- - currency
  - Three-letter ISO 4217 code for the currency used in the 'item' objects.
- - customer
  - ID of the customer. String starting with **cus_**.
- - email
  - Email address of the customer.
- - items
  - Each item describes one charge in this invoice. There must be one item of `type` = **shipping** and at least one item of `type` = **sku**.

    - - amount
      - Price of one SKU unit, in the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.
    - - currency
      - Three-letter ISO 4217 code for the currency. Must be the same as the currency of the order and the currency of the customer's payment method.
    - - description
      - Description of the item.
    - - parent
      - **Request:** ID of the SKU object that represents the product. String starting with **sku_**. Each SKU can appear in this list only one time, for items of type 'sku'. Required when `type` is **sku**. Must be **null** when `type` is **shipping**. One of the following:

        - ID of the SKU object. String starting with **sku_**
        - ID of the coupon. If generated by Rapyd, a string starting with **coupon_**.
    - - quantity
      - Quantity of the product in the line item. Integer. Required when `type` is **sku**.
    - - type
      - Type of line item. One of the following:

        - **discount** (Response only.)
        - **shipping**
        - **sku**
        - **tax** (Response only.)
- - metadata
  - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata").
- - shipping_address
  - Address to receive the shipment.

    - - canton
      - Name of the canton administrative subdivision, as used in banking.
    - - city
      - City portion of the address.

        Required for issuance of a card to the wallet contact. Required for creating a Visa card payment that requires 3DS.
    - - country
      - The two-letter ISO 3166-1 ALPHA-2 code for the country.

        Required for creating a Visa card payment that requires 3DS.
    - - district
      - Name of the district administrative subdivision, as used in banking.
    - - line_1
      - Line 1 of the address, such as a building number and street name.

        Required for creating a Visa card payment that requires 3DS.
    - - line_2
      - Line 2 of the address, such as a suite or apartment number, or the name of a named building.
    - - line_3
      - Line 3 of the address.
    - - metadata
      - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata").
    - - name
      - The name of a contact person or an "in care of" person at this address. For a **personal** wallet contact type, alphabetic characters and spaces.

        Required for creating a Visa card payment that requires 3DS.
    - - phone_number
      - Phone number associated with this specific address in E.164 format. Must be unique.

        Required for creating a Visa card payment that requires 3DS.
    - - state
      - State or province portion of the address.

        Required for creating a Visa card payment that requires 3DS.
    - - zip
      - Postal code portion of the address.

        Required for creating a Visa card payment that requires 3DS.
- - tax_percent
  - Percentage of tax to charge. Decimal 0-100, up to four decimal places.
- - upstream_id
  - Merchant-defined ID for the order.

### Response Parameters

- - amount
  - Total amount of the order, the sum of the amount of the shipping' items, plus the `amount` of the tax, plus `amount` times `quantity` of each of the `sku` items. Decimal.
- - amount_returned
  - Total amount of returns against the order. Decimal.
- - coupon
  - ID of a coupon that is applied against this order.
- - created
  - When the order was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").
- - currency
  - Three-letter ISO 4217 code for the currency used in the `item` objects.
- - customer
  - ID of the customer. String starting with **cus_**.
- - email
  - Email address of the customer.
- - external_coupon_code
  - ID of a coupon that is applied against this order, defined by the merchant. If generated by Rapyd, a string starting with **coupon_**.
- - id
  - Unique ID of the Order object. If the merchant does not define an ID, Rapyd generates a string starting with **order_**.
- - items
  - Each item describes one charge in this invoice. There must be one item of `type` = **shipping** and at least one item of `type` = **sku**.

    - - amount
      - Price of one SKU unit, in the currency defined in `currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015.
    - - currency
      - Three-letter ISO 4217 code for the currency. Must be the same as the currency of the order and the currency of the customer's payment method.
    - - description
      - Description of the item.
    - - parent
      - ID of the SKU object that represents the product. One of the following:

        - ID of the SKU object. String starting with **sku_**
        - ID of the coupon. If generated by Rapyd, a string starting with **coupon_**.
    - - quantity
      - Quantity of the product in the line item. Integer. Required when `type` is **sku**.
    - - type
      - Type of line item. One of the following:

        - **discount**
        - **shipping**
        - **sku**
        - **tax**
- - metadata
  - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata").
- - payment
  - Describes the collection efforts being made against this order.
- - payment_method
  - Payment method ID. String starting with **card_** or **other_**.

    If not specified in this field, the payment method is the default payment method specified for the customer.
- - returns
  - A list of the returns charged against this order.
- - shipping_address
  - Address to receive the shipment.

    - address
    - Billing address associated with the payment. For details about the fields of the 'address' object, see [Create Address](https://docs.rapyd.net/en/create-address.md "Create Address").
- - status
  - Indicates the status of the order. One of the following:

    - **created** - Created.
    - **pending** - The collection process has been started.
    - **paid** - Paid in full.
    - **canceled** - The total amount of returns against this order equal the total amount of the order.
    - **partial** - Some of the products have been delivered to the customer.
    - **fulfilled** - The products have been delivered to the customer.
    - **returned** - A return has been processed against this order.
- - status_transitions
  - Indicates the last time in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") that the order transitioned to one of the following statuses. A zero value for a status indicates that the order has never transitioned to it.

    - **canceled**
    - **fulfilled**
    - **paid**
    - **partial**
    - **pending**
    - **returned**
- - tax_percent
  - Percentage of tax to charge. Decimal 0-100, up to four decimal places.
- - updated
  - Time the order was last updated, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time").
- - upstream_id
  - Merchant-defined ID for the order.

### Code Samples

- - .NET

    - ```csharp
      using System;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      var metadata = new
                      {
                          merchant_defined = true
                      };

                      var items = new Object[]
                      {
                          new
                          {
                              type = "sku",
                              currency = "USD",
                              amount = 200,
                              quantity = 2,
                              parent = "sku_2cc9627661754e0a0b78397a62c9d9f2",
                              description = "Deluxe Gamer's Chair",
                          },
                          new
                          {
                              type = "shipping",
                              amount = 10,
                              currency = "USD",
                              description = "Shipping",
                          }
                      };

                      var shipping_address = new
                      {
                          name = "John Doe",
                          line_1 = "123 State Street",
                          line_2 = "Apt. 34",
                          line_3 = "",
                          city = "Anytown",
                          district = "",
                          canton = "",
                          state = "NY",
                          country = "US",
                          zip = "12345",
                          phone_number = "12125559999",
                          metadata,
                      };

                      var requestObj = new
                      {
                          customer = "cus_c697782cd18d3862e40e991fe4f0ca34",
                          currency = "USD",
                          external_coupon_code = "squeee",
                          items,
                          shipping_address,
                          tax_percent = 0,
                          upstream_id = "GZC12345",
                          email = "johndoe@rapyd.net",
                          metadata,
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/orders", request);

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```javascript
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {
            customer: 'cus_c697782cd18d3862e40e991fe4f0ca34',
            currency: 'USD',
            external_coupon_code: 'squeee',
            items: [
              {
                type: 'sku',
                currency: 'USD',
                amount: 200,
                quantity: 2,
                parent: 'sku_2cc9627661754e0a0b78397a62c9d9f2',
                description: "Deluxe Gamer's Chair"
              },
              {
                type: 'shipping',
                amount: 10,
                currency: 'USD',
                description: 'Shipping'
              }
            ],
            shipping_address: {
              name: 'John Doe',
              line_1: '123 State Street',
              line_2: 'Apt. 34',
              line_3: '',
              city: 'Anytown',
              district: '',
              canton: '',
              state: 'NY',
              country: 'US',
              zip: '12345',
              phone_number: '12125559999',
              metadata: {
                merchant_defined: true
              }
            },
            tax_percent: 0,
            upstream_id: 'GZC12345',
            email: 'johndoe@rapyd.net',
            metadata: {
              merchant_defined: true
            }
          };
          const result = await makeRequest('POST', '/v1/orders', body);

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```php
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      $body = [
          "customer" =>  "cus_c697782cd18d3862e40e991fe4f0ca34",
          "currency" =>  "USD",
          "external_coupon_code" =>  "squeee",
          "items" =>  array(
              array(
                  "type" =>  "sku",
                  "currency" =>  "USD",
                  "amount" =>  200,
                  "quantity" =>  2,
                  "parent" =>  "sku_2cc9627661754e0a0b78397a62c9d9f2",
                  "description" =>  "Deluxe Gamer's Chair"
              ),
              array(
                  "type" => "shipping",
                  "amount" =>  10,
                  "currency" =>  "USD",
                  "description" =>  "Shipping"
              )
          ),
          "shipping_address" => array(
              "name" => "John Doe",
              "line_1" => "123 State Street",
              "line_2" => "Apt. 34",
              "line_3" => "",
              "city" => "Anytown",
              "district" => "",
              "canton" => "",
              "state" => "NY",
              "country" => "US",
              "zip" => "12345",
              "phone_number" => "12125559999",
              "metadata" => array(
                  "merchant_defined" => true
              )
          )
          "tax_percent" =>  0,
          "upstream_id" =>  "GZC12345",
          "email" =>  "johndoe@rapyd.net",
          "metadata" =>  array(
              "merchant_defined" => true
          ),
      ];

      try {
          $object = make_request('post', '/v1/orders', $body);
          var_dump($object);
      } catch(Exception $e) {
          echo "Error =>  $e";
      }
      ?>
      ```
- - Python

    - ```python
      from pprint import pprint

      from utilities import make_request

      order = {
          "customer": "cus_c697782cd18d3862e40e991fe4f0ca34",
          "currency": "USD",
          "external_coupon_code": "squeee",
          "items": [
              {
                  "type": "sku",
                  "currency": "USD",
                  "amount": 200,
                  "quantity": 2,
                  "parent": "sku_2cc9627661754e0a0b78397a62c9d9f2",
                  "description": "Deluxe Gamer's Chair"
              },
              {
                  "type": "shipping",
                  "amount": 10,
                  "currency": "USD",
                  "description": "Shipping"
              }
          ],
          "shipping_address": {
              "name": "John Doe",
              "line_1": "123 State Street",
              "line_2": "Apt. 34",
              "line_3": "",
              "city": "Anytown",
              "district": "",
              "canton": "",
              "state": "NY",
              "country": "US",
              "zip": "12345",
              "phone_number": "12125559999",
              "metadata": {
                  "merchant_defined": True
              }
          },
          "tax_percent": 0,
          "upstream_id": "GZC12345",
          "email": "johndoe@rapyd.net",
          "metadata": {
              "merchant_defined": True
          }
      }
      result = make_request(method='post', path='/v1/orders', body=order)
      pprint(result)
      ```

- /v1/orders

- Create an Order
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/orders' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "customer": "cus_4e25112ac20e144ad073a614dc46934b",
      "currency": "USD",
      "items": [
          {
              "type": "sku",
              "currency": "USD",
              "amount": 200.00,
              "quantity": 2,
              "parent": "sku_6eb43887fd478baaf9223ec7ec17da21",
              "description": "Deluxe Gamer's Chair"
          },
          {
              "type": "shipping",
              "amount": 10.00,
              "currency": "USD",
              "description": "Shipping"
          }
      ],
      "shipping_address": {
          "name": "John Doe",
          "line_1": "123 First Street",
          "city": "Anytown",
          "state": "NY",
          "country": "US",
          "zip": "12345",
          "phone_number": "12125559999"
      },
      "upstream_id": "2025-11-18a",
      "email": "johndoe@rapyd.net"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "187bffe8-4c0e-453a-91ab-4787ebee48cc"
      },
      "data": {
          "id": "order_87b78d2923633ab410654749e8817895",
          "amount": 410,
          "amount_returned": 0,
          "payment": null,
          "created": 1763477605,
          "customer": "cus_4e25112ac20e144ad073a614dc46934b",
          "currency": "USD",
          "email": "johndoe@rapyd.net",
          "external_coupon_code": "",
          "items": [
              {
                  "amount": 200,
                  "currency": "USD",
                  "description": "Deluxe Gamer's Chair",
                  "parent": "sku_6eb43887fd478baaf9223ec7ec17da21",
                  "quantity": 2,
                  "type": "sku"
              },
              {
                  "amount": 10,
                  "currency": "USD",
                  "description": "Shipping",
                  "parent": "",
                  "quantity": 1,
                  "type": "shipping"
              }
          ],
          "metadata": {},
          "returns": [],
          "shipping_address": {
              "id": "address_a2472851af98bf84b818e4ffdfed6b01",
              "name": "John Doe",
              "line_1": "123 First Street",
              "line_2": "",
              "line_3": "",
              "city": "Anytown",
              "state": "NY",
              "country": "US",
              "zip": "12345",
              "phone_number": "12125559999",
              "metadata": {},
              "canton": "",
              "district": "",
              "created_at": 1763477606
          },
          "status": "created",
          "status_transitions": {
              "canceled": 0,
              "fulfilled": 0,
              "paid": 0,
              "returned": 0,
              "pending": 0,
              "partial": 0
          },
          "updated": 1763477605,
          "upstream_id": "2025-11-18a",
          "tax_percent": 0
      }
  }
  ```

- Bad Request - Currency Mismatch
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/orders' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "customer": "cus_4e25112ac20e144ad073a614dc46934b",
      "currency": "USD",
      "items": [
          {
              "type": "sku",
              "currency": "EUR",
              "amount": 200.00,
              "quantity": 2,
              "parent": "sku_6eb43887fd478baaf9223ec7ec17da21",
              "description": "Deluxe Gamer's Chair"
          },
          {
              "type": "shipping",
              "amount": 10.00,
              "currency": "USD",
              "description": "Shipping"
          }
      ],
      "shipping_address": {
          "name": "John Doe",
          "line_1": "123 First Street",
          "city": "Anytown",
          "state": "NY",
          "country": "US",
          "zip": "12345",
          "phone_number": "12125559999"
      },
      "upstream_id": "2025-11-18a",
      "email": "johndoe@rapyd.net"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_INVALID_ORDER_CURRENCY",
          "status": "ERROR",
          "message": "The request tried to create an order, but the currency of the order items did not match the currency of the order. The request was rejected. Corrective action: For 'currency' in each object in the 'items' array, use the currency of the order.",
          "response_code": "ERROR_INVALID_ORDER_CURRENCY",
          "operation_id": "76b1dab8-cc7e-4035-9a3c-792c21bef676"
      }
  }
  ```

- Bad Request - Item Type Not Valid
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/orders' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "customer": "cus_4e25112ac20e144ad073a614dc46934b",
      "currency": "USD",
      "items": [
          {
              "type": "skew",
              "currency": "USD",
              "amount": 200.00,
              "quantity": 2,
              "parent": "sku_6eb43887fd478baaf9223ec7ec17da21",
              "description": "Deluxe Gamer's Chair"
          },
          {
              "type": "shipping",
              "amount": 10.00,
              "currency": "USD",
              "description": "Shipping"
          }
      ],
      "shipping_address": {
          "name": "John Doe",
          "line_1": "123 First Street",
          "city": "Anytown",
          "state": "NY",
          "country": "US",
          "zip": "12345",
          "phone_number": "12125559999"
      },
      "upstream_id": "2025-11-18a",
      "email": "johndoe@rapyd.net"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_ORDER_ITEM_INVALID_TYPE",
          "status": "ERROR",
          "message": "The request tried to create an order, but the 'type' of an order item was not recognized. The request was rejected. Corrective action: Set 'type' to one of the following values: 'sku' or 'shipping'.",
          "response_code": "ERROR_ORDER_ITEM_INVALID_TYPE",
          "operation_id": "6e71aa87-c2a1-4a08-bca4-66eee2000e28"
      }
  }
  ```