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.

Responding to requests

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

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:

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:

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:

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.