Skip to content

Resolving Claims

To enable automated claims resolution, you'll need to set up your API endpoint and authenticate incoming requests from Onward. This API allows Onward to automatically resolve claims in your system.

Setting Up Your Endpoint

  1. Log in to your Onward Account.
  2. Navigate to the Claims Resolution API tab in your account settings
  3. Enter your API endpoint URL (e.g., https://api.your-store.com/claims).

This endpoint will receive requests from Onward for refunds, reorders, and store credits when claims are approved.

Authenticating Requests

Onward will authenticate all API calls to your endpoint by including your Onward API key in the X-API-Key header. You should validate this header matches the key shown in your account settings.

Keep your API key secure and validate it on all incoming requests to ensure they are legitimate calls from Onward.

Responding to requests

Your endpoint will need to handle three types of requests, as outlined in the Claims Resolution API documentation:

1. Refund Requests

When a claim is approved for a refund, Onward will send a POST request to your API endpoint. You must respond to this request with a 200 http status:

Flow diagram
curl -i -X POST \
  https://api.your-store.com/onward/orders/18282/refund \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_order_id": "18282",
    "onward_refundable": {
      "id": "456001",
      "type": "Claim"
    },
    "line_items": [
      {
        "to_issue_amount": {
          "currency": "USD",
          "cents": 1099
        },
        "to_issue_amount_presentment": {
          "currency": "CAD",
          "cents": 1525
        },
        "shop_line_item_id": "91827",
        "quantity_to_issue": 1
      }
    ]
  }'

2. Reorder Requests

When a claim is approved for a reorder, Onward will send a POST request to create a new order. You must respond with the new order details:

Flow diagram
curl -i -X POST \
  https://api.your-store.com/onward/orders/190102/reorder \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "onward_reorderable": {
      "id": "356001",
      "type": "Claim"
    },
    "line_items": [
      {
        "shop_line_item_id": "LI-1989",
        "quantity_to_issue": 0
      }
    ],
    "customer": {
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "phone_number": "string"
    },
    "shipping_address": {
      "address1": "123 Main St",
      "address2": "Unit 50",
      "province_code": "CA",
      "city": "Los Angeles",
      "postal_code": "90210",
      "country_code": "US",
      "phone_number": "+13105551234"
    }
  }'

3. Store Credit Requests

When a claim is approved for store credit, Onward will send a POST request to issue store credit. You must respond with the store credit ID, which will represent either a gift card or discount created in your system:

Flow diagram
curl -i -X POST \
  'https://api.your-store.com/onward/orders/{shopOrderId}/store_credit' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "customer": {
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "phone_number": "string"
    },
    "to_issue_amount": {
      "currency": "USD",
      "cents": 1099
    }
  }'

Error handling

Your endpoint should respond with appropriate HTTP status codes:

  • 200 for successful processing
  • 422 for validation errors (e.g., invalid order ID)
  • 401 for authentication failures
  • 500 for server errors

Include details about any errors in the response body to help with troubleshooting.

Previous page
Next page