This document outlines how to properly create and update orders in the Rydership API, with tips for avoiding common issues.

In this article:

• Creating Orders
• Troubleshooting not_found Errors When Posting an Order
• Updating Orders
• Order Types
• Shipping Method Mapping
• Using Meta Fields
• Example Order Creation Body

Creating Orders

When creating an order via the API, follow these best practices:

Include All Order Items in the Initial Request

Orders should be created in a single POST request with all associated order items included in the body. You can add additional order items in subsequent PUT's, but we do support creation of the entire order in one POST request.

Prevent Duplicate Orders with original_id

To prevent duplicate order creation, especially in retry scenarios, always pass a unique original_id in the request using the originator_attributes block. If Rydership sees the same original_id more than once, we will block duplicates. Ex:

"originator_attributes": {
    "original_id": "your_order_reference_here"
}

If no original_id is provided, the value will default to nil, and duplicate protection will not work.

Back to top

Troubleshooting not_found Errors When Posting an Order

If you receive a not_found error when posting an order, check the following:

1. Ensure all valid item_ids exist in Rydership
2. Verify your JSON formatting is correct and all required fields are present
3. Confirm the X-Customer-Id value is valid
4. Remove the X-Shop-Id header (this is not required and can cause issues)

Back to top

Updating Orders

Once an order is created, the following updates can be made via API:

Update Shipping Address or Method

Use PUT to update fields on the order itself:

PUT /orders/{{order_id}}

Add an Item to an Existing Order

POST /orders/{{order_id}}/order_items

Remove a Line Item from an Order

DELETE /order_items/{{order_item_id}}

Update Quantity on an Existing Item

PUT /order_items/{{order_item_id}}

Cancel an Order

PUT /orders/{{order_id}}/call/cancel

Back to top

Order Types

Specify the order_type in the request body. Supported values:

• retail
• wholesale
• direct_to_consumer
• dropship
• transfer
• value_added_service

Back to top

Shipping Method Mapping

Use the shop_shipping_method_text field to pass the shipping method name from your storefront/shopping cart. This will map to the official shipping methods you have configured in Rydership.

Manage shipping method mappings here:
https://www.getwhiplash.com/preferences?tab=shipping_methods

Back to top

Using Meta Fields

If you need to pass custom data with an order, use the meta_fields block. These fields must first be created and available in Rydership before they can be accepted via API. More on meta fields.

"meta_fields": {
    "fields": {
        "custom_flag": "true"
    }
}

Back to top

Example Order Creation Body

Below is a sample payload for creating an order via POST /orders:

{
    "shipping_state": "CA",
    "email": "test@example.com",
    "shipping_city": "Los Angeles",
    "shipping_address_1": "123 Main St",
    "last_name": "Doe",
    "first_name": "Jane",
    "shipping_phone": "+1 555 555 5555",
    "shipping_zip": "90001",
    "shipping_country": "US",
    "order_items": [
        {
            "quantity": 1,
            "item_id": 3104926
        },
        {
            "quantity": 1,
            "item_id": 3104937
        },
        {
            "quantity": 1,
            "item_id": 3104938
        }
    ],
    "order_orig": "webINV12345",
    "shop_shipping_method_text": "FedEx Home Delivery",
    "order_type": "direct_to_consumer",
    "shipping_name": "Jane Doe",
    "originator_attributes": {
        "original_id": "webINV12345"
    },
    "meta_fields": {
        "fields": {
            "influencer_order": "true"
        }
    }
}

Back to top

See the API Developer Library for the complete V2 RyderShip developer documentation.