Testing orders with the REST Admin API

You can use the REST Admin API to create test orders and transactions to validate your app's behavior.

To avoid platform fees, follow this recommended workflow for testing orders:

  1. Create an order with an authorized transaction.
  2. Get a transaction ID to use as a parent ID when capturing the transaction.
  3. Capture the transaction and set the test property to true on the order.

Other methods, such as using a manual payment gateway and the cash on delivery payment method, don't create a test order and are subject to platform fees.

Before you begin

To best understand this guide, you can familiarize yourself with the concepts of orders and transactions. Transactions are associated to orders and occur each time there is an exchange of money. Transactions are processed by payment providers, and involve the transfer of money from the issuer account (the customer's credit card) to the acquirer (the merchant's bank account). For more information, see Getting paid.

Create an order

To test orders, create an order with an authorization transaction by sending a POST request to the Order resource. Include the transactions object in the body of the request:

POST https://{shop}.myshopify.com/admin/api/2019-07/orders.json

{
  "order": {
    "email": " ",
    "financial_status": "pending",
    "line_items": [
      {
        "title": "Big Brown Bear Boots",
        "price": 100,
        "grams": "1300",
        "quantity": 2,
        "tax_lines": [
          {
            "price": 13.5,
            "rate": 0.06,
            "title": "State tax"
          }
        ]
      }
    ],
    "transactions": [
      {
        "kind": "authorization",
        "status": "success",
        "amount": 200
      }
    ]
  }
}

Response:

View response

{
    "order": {
        "id": 1165756760120,
        "email": "",
        "closed_at": null,
        "created_at": "2019-04-03T17:39:55-04:00",
        "updated_at": "2019-04-03T17:39:55-04:00",
        "number": 90,
        "note": null,
        "token": "07867cf3c1b2508b4310adaf9fce9ba9",
        "gateway": "",
        "test": false,
        "total_price": "200.00",
        "subtotal_price": "200.00",
        "total_weight": 0,
        "total_tax": "0.00",
        "taxes_included": false,
        "currency": "USD",
        "financial_status": "pending",
        "confirmed": true,
        "total_discounts": "0.00",
        "total_line_items_price": "200.00",
        "cart_token": null,
        "buyer_accepts_marketing": false,
        "name": "#1090",
        "referring_site": null,
        "landing_site": null,
        "cancelled_at": null,
        "cancel_reason": null,
        "total_price_usd": "200.00",
        "checkout_token": null,
        "reference": null,
        "user_id": null,
        "location_id": null,
        "source_identifier": null,
        "source_url": null,
        "processed_at": "2019-04-03T17:39:55-04:00",
        "device_id": null,
        "phone": null,
        "customer_locale": null,
        "app_id": 2802623,
        "browser_ip": null,
        "landing_site_ref": null,
        "order_number": 1090,
        "discount_applications": [],
        "discount_codes": [],
        "note_attributes": [],
        "payment_gateway_names": [
            ""
        ],
        "processing_method": "",
        "checkout_id": null,
        "source_name": "2802623",
        "fulfillment_status": null,
        "tax_lines": [
            {
                "price": "13.50",
                "rate": 0.06,
                "title": "State tax",
                "price_set": {
                    "shop_money": {
                        "amount": "13.50",
                        "currency_code": "USD"
                    },
                    "presentment_money": {
                        "amount": "13.50",
                        "currency_code": "USD"
                    }
                }
            }
        ],
        ...
    }
}

Get a transaction ID

After you create the order, the returned Order object includes an ID. You can then use the order ID to return the transaction and its ID. To retrieve the transaction, send a GET request to the Order Transaction resource:

GET https://{shop}.myshopify.com/admin/api/2019-07/orders/{order_id}/transactions.json

Response:

View response

{
    "transactions": [
        {
            "id": 1458851250232,
            "order_id": 1165756760120,
            "kind": "authorization",
            "gateway": "",
            "status": "success",
            "message": null,
            "created_at": "2019-04-03T17:39:55-04:00",
            "test": false,
            "authorization": null,
            "location_id": null,
            "user_id": null,
            "parent_id": null,
            "processed_at": "2019-04-03T17:39:55-04:00",
            "device_id": null,
            "receipt": {},
            "error_code": null,
            "source_name": "2802623",
            "amount": "200.00",
            "currency": "USD",
            "admin_graphql_api_id": "gid://shopify/OrderTransaction/1458851250232"
        }
    ]
}

Capture the transaction

After you return the transaction, you can use its ID to create a capture transaction to capture payment. To create the capture transaction, send a Transaction object in the body of a POST request to the Order Transaction resource with the transaction ID of the authorization as the parent_id and the test property set to true:

POST https://{shop}.myshopify.com/admin/api/2019-07/orders/{order_id}/transactions.json

{
  "transaction": {
    "currency": "USD",
    "amount": "200.00",
    "kind": "capture",
    "parent_id": 1458851250232,
    "test": "true"
  }
}

Response:

View response

{
    "transaction": {
        "id": 1458851708984,
        "order_id": 1165756760120,
        "kind": "capture",
        "gateway": "",
        "status": "success",
        "message": "Marked the payment as received",
        "created_at": "2019-04-03T17:49:07-04:00",
        "test": true,
        "authorization": null,
        "location_id": null,
        "user_id": null,
        "parent_id": 1458851250232,
        "processed_at": "2019-04-03T17:49:07-04:00",
        "device_id": null,
        "receipt": {},
        "error_code": null,
        "source_name": "2802623",
        "amount": "200.00",
        "currency": "USD",
        "admin_graphql_api_id": "gid://shopify/OrderTransaction/1458851708984"
    }
}

Confirm the test order

After you've followed the steps above, you can retrieve the order to verify that it is in test mode. If the order is a test order, then the response includes the test property set to true:

GET https://{shop}.myshopify.com/admin/api/2019-07/orders/{order_id}.json

Response:

View response

{
    "order": {
        "id": 1165756760120,
        "email": "",
        "closed_at": null,
        "created_at": "2019-04-03T17:39:55-04:00",
        "updated_at": "2019-04-03T17:49:07-04:00",
        "number": 90,
        "note": null,
        "token": "07867cf3c1b2508b4310adaf9fce9ba9",
        "gateway": "",
        "test": true,
        ...
    }
}

Sign up for a Partner account to get started.

Sign up