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

# Update an Order

Change or modify an order.

You can make the following changes:

- When `status` is **created**: `coupon`, `metadata` or `tax_percent` fields.
- When `status` is **pending**, **paid**, or **fulfilled**: `metadata` or `status` fields.

When the customer completes a payment, the merchant must change the `status` from **pending** to **paid**.

This method triggers the [Order Updated Webhook](https://docs.rapyd.net/en/order-updated-webhook.md "Order Updated 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 Path Parameters

- - order
  - ID of the order.

### 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**.
- - metadata
  - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata").
- - status
  - Indicates the status of the order. Can be changed when `status` is **pending**, **paid**, or **fulfilled**. 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.
- - tax_percent
  - Percentage of tax to charge. Decimal 0-100, up to four decimal places.

### 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).

### 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
                  {
                      string order = "order_20bdf9df5841e57ba80e0a68085871ea";

                      var metadata = new
                      {
                          merchant_defined = true
                      };

                      var requestObj = new
                      {
                          metadata,
                          tax_percent = 13.5,
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/orders/{order}", 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 = {
            metadata: {
              number: 1
            }
          };
          const result = await makeRequest(
            'POST',
            '/v1/orders/order_20bdf9df5841e57ba80e0a68085871ea',
            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 = [
          "tax_percent" => 13.5
      ];

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

    - ```python
      from pprint import pprint

      from utilities import make_request

      order = {
          "metadata": {
              "merchant_defined": True
          },
          "tax_percent": 13.5
      }
      result = make_request(method='post', path='/v1/orders/order_20bdf9df5841e57ba80e0a68085871ea', body=order)
      pprint(result)
      ```

- /v1/orders/:order

- Tax Percent
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/orders/order_87b78d2923633ab410654749e8817895' \
  -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 '{
      "tax_percent": 11.5
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "969eb097-1428-41fb-bbdf-f77228c5ff11"
      },
      "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"
              },
              {
                  "amount": 47.15,
                  "currency": "USD",
                  "description": "11.5% tax on total order",
                  "parent": "",
                  "quantity": 0,
                  "type": "tax"
              }
          ],
          "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": 1763477992,
          "upstream_id": "2025-11-18a",
          "tax_percent": 11.5
      }
  }
  ```

- Status
- ```curl
  curl -X post  -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 '{
  	"status": "partial"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "cdac3445-3568-45bb-89bf-cd616d74482c"
      },
      "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"
              },
              {
                  "amount": 47.15,
                  "currency": "USD",
                  "description": "11.5% tax on total order",
                  "parent": "",
                  "quantity": 0,
                  "type": "tax"
              }
          ],
          "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": "partial",
          "status_transitions": {
              "canceled": 0,
              "fulfilled": 0,
              "paid": 0,
              "returned": 0,
              "pending": 0,
              "partial": 0
          },
          "updated": 1763478219,
          "upstream_id": "2025-11-18a",
          "tax_percent": 11.5
      }
  }
  ```

- Bad Request - Order Already Paid
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/orders/order_2eab913cd3d5780ccbc85b0208343150' \
  -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 '{
      "tax_percent": 10.25
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_ORDER_TAX_FIELD_NOT_UPDATABLE",
          "status": "ERROR",
          "message": "The request tried to update the 'tax_percent' body parameter of an order, but the order status was not 'new'. An order can only be updated when the status is 'new.' The request was rejected. Corrective action: Create a new order and add the correct value to the 'tax_percent' field.",
          "response_code": "ERROR_ORDER_TAX_FIELD_NOT_UPDATABLE",
          "operation_id": "125186a0-189d-47ac-8d00-198e3ece0019"
      }
  }
  ```

- Bad Request - Status Not Valid
- ```curl
  curl -X post  -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 '{
  	"status": "closed"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_ORDER_INVALID_STATUS",
          "status": "ERROR",
          "message": "The request tried to update the status of an order, but the status was not valid. The request was rejected. Corrective action: Set 'status' to one of the following values: 'canceled', 'fulfilled', 'paid', 'pending', 'partial' or 'returned.",
          "response_code": "ERROR_ORDER_INVALID_STATUS",
          "operation_id": "23397f42-d028-4595-a5d1-1934add315b1"
      }
  }
  ```