Once you’ve created your Product Variations, you can move on to creating Orders and directing your customers to the checkout page.

🔗 If you haven’t created a Product Variation yet, see the guide here: Create Product Variations on Purpl using Rest client like Postman

🧍 Step 1: Create an Order

To create an Order, send a POST request to the /orders/ endpoint.

Example Request

POST /orders/
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

Example Body

{
  "customer": {
    "name": "John Doe",
    "phone_number": "+1234567890",
    "email": "[email protected]"
  },
  "merchant_reference": "lakdvjbiu" // Unique identifier on your end [max length is 36]
  "lines": [
    {
      "item": {
        "type": "product-variation",
        "id": 12
      },
      "unit_price": {
        "currency": "USD",
        "value": "15.00"
      },
      "quantity": 1
    }
  ],
  "amount": {
    "currency": "USD",
    "value": "15.00"
  }
}

Field Explanation

Field Description
customer Basic customer details — name is required; others are optional.
lines Items being ordered. Each item should reference a Product Variation ID.
unit_price Price per unit of the product being ordered.
quantity Number of units ordered.
amount The total order value (should match unit price × quantity).
merchant_reference A Unique Identifier on your end to retrieve the specific order by passing it as a query parameter.
Example:
GET /orders/?merchant_reference=<my_unique_id>

Once the order is successfully created, you’ll receive a response containing the Order ID (UUID format).

💳 Step 2: Redirect Customer to Checkout

Use the Order ID to redirect your customer to the checkout page.

https://checkout.test.purplme.com/?orderId=<ORDER_UUID>

Optional Query Parameters

You can customize the checkout experience using these additional query parameters:

Parameter Type Description
showSuccessPage true / false Whether to show Purpl’s built-in success page after payment. If false, the user will be redirected directly to your returnUrl.
method wallet / card
successUrl string (URL) The URL on your site to which the customer will be redirected after payment success. Appears as a “Back to merchant” button on the success page (if shown).
failedUrl string (URL) The URL on your site to which the customer will be redirected after payment failed. Appears as a “Back to merchant” button on the success page (if shown).