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. This webhook contains the same information as the response.

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

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.
- 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.
- 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.
- 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 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.
- upstream_id
- Merchant-defined ID for the order.

Code Samples

.NET

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

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
$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

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 -X post
https://sandboxapi.rapyd.net/v1/orders/order_90c6a004eb51af10ad8521de4d984a22
-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'
-d '{
    "metadata": {
        "merchant_defined": true
    },
    "tax_percent": 15,
    "coupon": ""
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "c737c893-5c3a-4e52-b850-4189e350a736"
    },
    "data": {
        "id": "order_90c6a004eb51af10ad8521de4d984a22",
        "amount": 471.5,
        "amount_returned": 0,
        "payment": null,
        "created": 1596103588,
        "customer": "cus_bb2efee62c0179f563f0d29ba5001051",
        "currency": "USD",
        "email": "johndoe@rapyd.net",
        "external_coupon_code": "",
        "items": [
            {
                "amount": 10,
                "currency": "USD",
                "description": "Shipping",
                "parent": "",
                "quantity": 1,
                "type": "shipping"
            },
            {
                "amount": 200,
                "currency": "USD",
                "description": "Deluxe Gamer's Chair",
                "parent": "sku_46976a7be5c29d2b2073059877751419",
                "quantity": 2,
                "type": "sku"
            },
            {
                "amount": 61.5,
                "currency": "USD",
                "description": "15% tax on total order",
                "parent": "",
                "quantity": 0,
                "type": "tax"
            }
        ],
        "metadata": {
            "merchant_defined": true
        },
        "returns": [],
        "shipping_address": {
            "id": "address_9eb6deb646a279dbdc423f07fa4121ba",
            "name": "John Doe",
            "line_1": "",
            "line_2": "",
            "line_3": "",
            "city": "Anytown",
            "state": "NY",
            "country": "US",
            "zip": "12345",
            "phone_number": "12125559999",
            "metadata": {
                "merchant_defined": true
            },
            "canton": "",
            "district": "",
            "created_at": 1596103588
        },
        "status": "created",
        "status_transitions": {
            "canceled": 0,
            "fulfilled": 0,
            "paid": 0,
            "returned": 0,
            "pending": 0,
            "partial": 0
        },
        "updated": 1596103988,
        "upstream_id": "GZC12345",
        "tax_percent": 15
    }
}

Status

// Request URL: POST https://sandboxapi.rapyd.net/v1/orders/order_fc5bbe669e7ab546a0f705fe9b90817a

// Message body:
{
	"status": "paid"
}

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "e954d9a6-eaeb-41da-8b87-77c72363d6cd"
    },
    "data": {
        "id": "order_fc5bbe669e7ab546a0f705fe9b90817a",
        "amount": 410,
        "amount_returned": 0,
        "payment": null,
        "created": 1636980756,
        "customer": "cus_8d73840a409c849a0f715ee2fc114410",
        "currency": "USD",
        "email": "johndoe@rapyd.net",
        "external_coupon_code": "",
        "items": [
            {
                "amount": 200,
                "currency": "USD",
                "description": "Deluxe Gamer's Chair",
                "parent": "sku_8d345036a8520fa7e31d396b97502b19",
                "quantity": 2,
                "type": "sku"
            },
            {
                "amount": 10,
                "currency": "USD",
                "description": "Shipping",
                "parent": "",
                "quantity": 1,
                "type": "shipping"
            }
        ],
        "metadata": {
            "merchant_defined": true
        },
        "returns": [],
        "shipping_address": {
            "id": "address_43bd104eac45bcfcf3dc41d125b8c0d9",
            "name": "John Doe",
            "line_1": "",
            "line_2": "",
            "line_3": "",
            "city": "Anytown",
            "state": "NY",
            "country": "US",
            "zip": "12345",
            "phone_number": "12125559999",
            "metadata": {
                "merchant_defined": true
            },
            "canton": "",
            "district": "",
            "created_at": 1636980756
        },
        "status": "paid",
        "status_transitions": {
            "canceled": 0,
            "fulfilled": 0,
            "paid": 1637068431,
            "returned": 0,
            "pending": 1637053897,
            "partial": 0
        },
        "updated": 1637068431,
        "upstream_id": "GZC12345",
        "tax_percent": 0
    }
}

In this section:

Documentation