Order Object

⚙️ API 🙋🏽‍♀️🙋🏽‍♂️ Ask Questions
1

A question was asked on the Order Object, it’s use case and updating the status of an order. The Rapyd API includes the Order Object for certain products that are goods like coffee beans, electronics, or furniture. These are one time orders that are delivered to an address.

Follow the steps to create an order.

Create Product

Use "type": "goods", to create a product to retrieve your product ID

Product ID: product_7c637548e97489f9101a01ce17f452c2

Create SKU

Create a SKU (Stock Keeping Unit) using the Product ID.

Request

{
  "id": "",
  "active": true,
  "attributes": {
  	"color": "green"
  },
  "currency": "USD",
    "images": [
        "64bit-encoded-image-1",
        "64bit-encoded-image-2"
    ],
  "inventory": {
    "quantity": 1, 
    "type": "finite", 
    "value": 600
  },
   "metadata": {
     "merchant_defined": "red_chair"
   },
  "package_dimensions": {
 "height": 10,
            "length": 20,
            "weight": 30,
            "width": 40
  },
  "price": 600,

  "product": "product_c26a459a12ffb261ff00d4c860499a76"
}

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "f3cb678a-01f3-4870-92de-9a7857fa38f8"
    },
    "data": {
        "id": "sku_3fc5f0af4eba92f2a9ac18e36bd25927",
        "active": true,
        "attributes": {
            "color": "green"
        },
        "created_at": 1652486232,
        "currency": "USD",
        "image": "",
        "inventory": {
            "type": "finite",
            "quantity": 1,
            "value": ""
        },
        "metadata": {
            "merchant_defined": "red_chair"
        },
        "price": 600,
        "product": "product_c26a459a12ffb261ff00d4c860499a76",
        "package_dimensions": {
            "length": 20,
            "height": 10,
            "weight": 30,
            "width": 40
        },
        "updated_at": 1652486232
    }
}

Create Order

Create Order using the Customer ID and SKU ID.

Request

{
    "customer": "cus_11f7783b2c80f53400ab33095055f7cb",
    "currency": "USD",
    "external_coupon_code": "squeee",
    "items": [
        {
            "type": "sku",
            "currency": "USD",
            "amount": 600,
            "quantity": 1,
            "parent": "sku_3fc5f0af4eba92f2a9ac18e36bd25927",
            "description": "Deluxe Gamer's Chair"
        }, 
        {
            "type": "shipping",
            "amount": 1,
            "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
    }
}

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "2b852dee-c168-4121-910a-49d248743f24"
    },
    "data": {
        "id": "order_ec0b8d6e8d76a3066356e553435bd96a",
        "amount": 601,
        "amount_returned": 0,
        "payment": null,
        "created": 1652486375,
        "customer": "cus_11f7783b2c80f53400ab33095055f7cb",
        "currency": "USD",
        "email": "johndoe@rapyd.net",
        "external_coupon_code": "",
        "items": [
            {
                "amount": 600,
                "currency": "USD",
                "description": "Deluxe Gamer's Chair",
                "parent": "sku_3fc5f0af4eba92f2a9ac18e36bd25927",
                "quantity": 1,
                "type": "sku"
            },
            {
                "amount": 1,
                "currency": "USD",
                "description": "Shipping",
                "parent": "",
                "quantity": 1,
                "type": "shipping"
            }
        ],
        "metadata": {
            "merchant_defined": true
        },
        "returns": [],
        "shipping_address": {
            "id": "address_64011fe320db2f1b74b04ed96a4d2b55",
            "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": 1652486375
        },
        "status": "created",
        "status_transitions": {
            "canceled": 0,
            "fulfilled": 0,
            "paid": 0,
            "returned": 0,
            "pending": 0,
            "partial": 0
        },
        "updated": 1652486375,
        "upstream_id": "GZC12345",
        "tax_percent": 0
    }
}

Retreive Order

When Retrieving order, the status still shows as created.

Update Order

You can update status from created to pending , paid , or fulfilled

Request
Use the Order ID in the query paramers

Request Body

{
	"metadata": {
		"merchant_defined": true
	},
    "status":"fulfilled"
}

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "1264e029-6247-4b30-b3a5-852f00b982dc"
    },
    "data": {
        "id": "order_ec0b8d6e8d76a3066356e553435bd96a",
        "amount": 601,
        "amount_returned": 0,
        "payment": null,
        "created": 1652486375,
        "customer": "cus_11f7783b2c80f53400ab33095055f7cb",
        "currency": "USD",
        "email": "johndoe@rapyd.net",
        "external_coupon_code": "",
        "items": [
            {
                "amount": 600,
                "currency": "USD",
                "description": "Deluxe Gamer's Chair",
                "parent": "sku_3fc5f0af4eba92f2a9ac18e36bd25927",
                "quantity": 1,
                "type": "sku"
            },
            {
                "amount": 1,
                "currency": "USD",
                "description": "Shipping",
                "parent": "",
                "quantity": 1,
                "type": "shipping"
            }
        ],
        "metadata": {
            "merchant_defined": true
        },
        "returns": [],
        "shipping_address": {
            "id": "address_64011fe320db2f1b74b04ed96a4d2b55",
            "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": 1652486375
        },
        "status": "fulfilled",
        "status_transitions": {
            "canceled": 0,
            "fulfilled": 1652487222,
            "paid": 1652487205,
            "returned": 0,
            "pending": 1652487170,
            "partial": 0
        },
        "updated": 1652487222,
        "upstream_id": "GZC12345",
        "tax_percent": 0
    }
}
2 Likes
2

Also provided by our team member, @Community_Team.

In comparison, the Checkout Page Object provides a GUI (hosted page or toolkit) for you to collect an amount of money. You just specify what the amount is.

The Order object, on the other hand, is a representation of a list of products or services, that you are looking to collect money for. It works together with the Products object and the SKU object, and lets you specify a list of items (products/services) with the amount each costs, as well as the specific details of the product/service by using SKU entries.

You can collect the payment with the Pay an Order endpoint, and the order status will be marked as paid (depending on the payment method), and you will receive the relevant webhooks.

You can update the status only in these cases:

  • When status is created: coupon, metadata or tax_percent fields.
  • When status is pending, paid, or fulfilled: metadata or status fields.

For example, you might want to change the status from paid to fulfilled, once you delivered the products. Or from fulfilled to returned, if the user asked for a refund.

2 Likes
3

Didn’t know Rapyd had an API endpoint for managing products, very helpful for my use case!
I just have one quick question: Is it possible to generate a hosted checkout page from an order? Or do we have to create a checkout page based on the amount and update the order status via the API once the customer completes the payment?

2 Likes
4

Thanks @elbourki, currently there is no Hosted Page for the Order Object and only via API integration. You will have to create a checkout page based on the amount and update of the order states via the API.

However there are some developments with the Hosted Page for Subscriptions, as I commented through the link.

This relates since both Order Object and Subscriptions use the Product ID.