{
  "openapi": "3.0.3",
  "info": {
    "title": "Callbacks",
    "description": "Onward calls these endpoints in your system to issue order refunds, reorders, store credit, protection refunds, and loyalty rewards. Events on our side trigger them, such as resolving a claim, a customer opting out of protection, or cashback being earned on an order. Register your callback URL in our system and respond to the requests described below.",
    "termsOfService": "https://useonward.com/terms-and-conditions",
    "contact": {
      "email": "help@useonward.com"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.your-store.com/onward"
    }
  ],
  "paths": {
    "/orders/{shopOrderId}/refund": {
      "post": {
        "summary": "Refund an order",
        "description": "Onward is requesting a refund of products for the specified Order in your platform. The `onward_refundable` object identifies the record that triggered the refund (for example, a Claim).",
        "operationId": "refundOrder",
        "parameters": [
          {
            "$ref": "#/components/parameters/ContentType"
          },
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "name": "shopOrderId",
            "in": "path",
            "description": "Your ID for the Order",
            "required": true,
            "example": "18282",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "shop_order_id": {
                    "type": "string",
                    "description": "Your ID for the Order this refund relates to",
                    "example": "18282"
                  },
                  "onward_refundable": {
                    "type": "object",
                    "description": "Record that triggered this refund",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int32",
                        "description": "Our ID",
                        "example": "456001"
                      },
                      "type": {
                        "type": "string",
                        "description": "Kind of record",
                        "example": "Claim"
                      }
                    },
                    "required": [
                      "id",
                      "type"
                    ]
                  },
                  "line_items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "to_issue_amount": {
                          "description": "Amount to refund in the specified currency",
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string",
                              "example": "USD"
                            },
                            "cents": {
                              "type": "integer",
                              "format": "int32",
                              "example": 1099
                            }
                          }
                        },
                        "to_issue_amount_presentment": {
                          "description": "Amount to refund in the currency the customer uses",
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string",
                              "example": "CAD"
                            },
                            "cents": {
                              "type": "integer",
                              "format": "int32",
                              "example": 1525
                            }
                          }
                        },
                        "shop_line_item_id": {
                          "type": "string",
                          "description": "Your ID for the line item being refunded",
                          "example": "91827"
                        },
                        "quantity_to_issue": {
                          "type": "integer",
                          "format": "int32",
                          "description": "Number of items to refund",
                          "example": 1
                        }
                      },
                      "required": [
                        "to_issue_amount",
                        "to_issue_amount_presentment",
                        "shop_line_item_id",
                        "quantity_to_issue"
                      ]
                    }
                  }
                },
                "required": [
                  "shop_order_id",
                  "line_items",
                  "onward_refundable"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order refunded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shop_refund_id": {
                      "type": "string",
                      "description": "Your ID for the refund",
                      "example": "123456"
                    }
                  },
                  "required": [
                    "shop_refund_id"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Order not found"
          },
          "422": {
            "description": "Validation exception"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/orders/{shopOrderId}/refund_protection": {
      "post": {
        "summary": "Refund an order's protection",
        "description": "Onward is requesting a refund of the Onward protection premium for the specified Order in your platform, for example when a customer opts out of protection.",
        "operationId": "refundOrderProtection",
        "parameters": [
          {
            "$ref": "#/components/parameters/ContentType"
          },
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "name": "shopOrderId",
            "in": "path",
            "description": "Your ID for the Order",
            "required": true,
            "example": "18282",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "protection_amount": {
                    "description": "The Onward protection premium to refund, in the shop's currency",
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Money"
                      }
                    ]
                  }
                },
                "required": [
                  "protection_amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Protection refunded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shop_refund_id": {
                      "type": "string",
                      "description": "Your ID for the refund",
                      "example": "123456"
                    }
                  },
                  "required": [
                    "shop_refund_id"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Order not found"
          },
          "422": {
            "description": "Validation exception"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/orders/{shopOrderId}/reorder": {
      "post": {
        "summary": "Reorder items",
        "description": "Onward is requesting a reorder of products for the Order in your platform.\nIn addition to replying with `shop_order_id` & `shop_order_number` you also need to send the order in the regular channel (`POST /orders`).\n",
        "operationId": "reorderOrder",
        "parameters": [
          {
            "$ref": "#/components/parameters/ContentType"
          },
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "name": "shopOrderId",
            "in": "path",
            "description": "Your ID for the original Order",
            "required": true,
            "example": "190102",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "onward_reorderable": {
                    "type": "object",
                    "description": "Record that triggered this reorder",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int32",
                        "description": "Our ID",
                        "example": "356001"
                      },
                      "type": {
                        "type": "string",
                        "description": "Kind of record",
                        "example": "Claim"
                      }
                    },
                    "required": [
                      "id",
                      "type"
                    ]
                  },
                  "line_items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "shop_line_item_id": {
                          "type": "string",
                          "description": "The line item ID from the original order",
                          "example": "LI-1989"
                        },
                        "quantity_to_issue": {
                          "type": "integer",
                          "description": "The quantity to reorder"
                        }
                      },
                      "required": [
                        "shop_line_item_id",
                        "quantity_to_issue"
                      ]
                    }
                  },
                  "customer": {
                    "type": "object",
                    "properties": {
                      "first_name": {
                        "type": "string"
                      },
                      "last_name": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string",
                        "format": "email"
                      },
                      "phone_number": {
                        "type": "string"
                      }
                    }
                  },
                  "shipping_address": {
                    "$ref": "#/components/schemas/Address"
                  }
                },
                "required": [
                  "shipping_address",
                  "customer",
                  "line_items",
                  "onward_reorderable"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reorder created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shop_order_id": {
                      "type": "string",
                      "description": "Your ID for the new Order",
                      "example": "123456"
                    },
                    "shop_order_number": {
                      "type": "string",
                      "description": "The Order Number of this new Order as presented to the customer",
                      "example": "IN-94713"
                    }
                  },
                  "required": [
                    "shop_order_id",
                    "shop_order_number"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Order not found"
          },
          "422": {
            "description": "Validation exception"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/orders/{shopOrderId}/store_credit": {
      "post": {
        "summary": "Issue store credit",
        "description": "Onward is requesting store credit to be issued for a specific Order in your platform.",
        "operationId": "issueStoreCredit",
        "parameters": [
          {
            "$ref": "#/components/parameters/ContentType"
          },
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "name": "shopOrderId",
            "in": "path",
            "description": "Your ID for the Order",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customer": {
                    "type": "object",
                    "properties": {
                      "first_name": {
                        "type": "string"
                      },
                      "last_name": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string",
                        "format": "email"
                      },
                      "phone_number": {
                        "type": "string"
                      }
                    }
                  },
                  "to_issue_amount": {
                    "description": "Amount to refund in the specified currency",
                    "type": "object",
                    "properties": {
                      "currency": {
                        "type": "string",
                        "example": "USD"
                      },
                      "cents": {
                        "type": "integer",
                        "format": "int32",
                        "example": 1099
                      }
                    },
                    "required": [
                      "currency",
                      "cents"
                    ]
                  }
                },
                "required": [
                  "customer",
                  "to_issue_amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Store credit issued successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shop_store_credit_code": {
                      "type": "string",
                      "description": "The customer-facing code for the store credit",
                      "example": "GC123456"
                    },
                    "shop_store_credit_id": {
                      "type": "string",
                      "description": "Your internal ID for the store credit",
                      "example": "SC789"
                    },
                    "initial_value": {
                      "type": "object",
                      "description": "Initial balance of this store credit",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "example": "USD"
                        },
                        "cents": {
                          "type": "integer",
                          "format": "int32",
                          "example": 1099
                        }
                      }
                    },
                    "balance": {
                      "type": "object",
                      "description": "Current balance of this store credit",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "example": "USD"
                        },
                        "cents": {
                          "type": "integer",
                          "format": "int32",
                          "example": 1099
                        }
                      }
                    },
                    "note": {
                      "type": "string",
                      "description": "Any note for this store credit"
                    }
                  },
                  "required": [
                    "shop_store_credit_code",
                    "shop_store_credit_id",
                    "initial_value",
                    "balance"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Order not found"
          },
          "422": {
            "description": "Validation exception"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/customers/{shopCustomerId}/reward": {
      "post": {
        "summary": "Issue a reward",
        "description": "Onward is requesting a reward to be issued for the specified Customer in your platform, for example when an order earns cashback. One request is sent per credit.",
        "operationId": "issueReward",
        "parameters": [
          {
            "$ref": "#/components/parameters/ContentType"
          },
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "name": "shopCustomerId",
            "in": "path",
            "description": "Your ID for the Customer",
            "required": true,
            "example": "7461",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customer": {
                    "$ref": "#/components/schemas/Customer"
                  },
                  "to_issue_amount": {
                    "description": "Amount to credit, in the shop's currency",
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Money"
                      }
                    ]
                  },
                  "onward_reward_transaction_id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Our ID for this specific credit. Stable across retries — a repeated request with the same value should return the same shop_transaction_id rather than issuing a second credit.",
                    "example": 456001
                  }
                },
                "required": [
                  "customer",
                  "to_issue_amount",
                  "onward_reward_transaction_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reward issued successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shop_transaction_id": {
                      "type": "string",
                      "description": "Your ID for this credit",
                      "example": "rw_789"
                    },
                    "shop_reward_id": {
                      "type": "string",
                      "description": "Your ID for the redemption method (discount code, store credit, etc) the credit was added to. Onward stores it on the customer's reward.",
                      "example": "1234567890"
                    }
                  },
                  "required": [
                    "shop_transaction_id",
                    "shop_reward_id"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Customer not found"
          },
          "422": {
            "description": "Validation exception"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "ContentType": {
        "name": "Content-Type",
        "in": "header",
        "required": true,
        "example": "application/json",
        "description": "Content-Type must be application/json",
        "schema": {
          "type": "string"
        }
      },
      "Accept": {
        "name": "Accept",
        "in": "header",
        "required": true,
        "example": "application/json",
        "description": "Accept must be application/json",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Order": {
        "type": "object",
        "properties": {
          "shop_order_id": {
            "type": "string",
            "description": "Your ID for the Order",
            "example": "18282"
          },
          "shop_order_number": {
            "type": "string",
            "description": "The Order Number as presented to the customer",
            "example": "W-94713"
          },
          "subtotal_price": {
            "description": "Order subtotal in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "subtotal_price_presentment": {
            "description": "Order subtotal in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_discounts_price": {
            "description": "Sum of applied discounts in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_discounts_price_presentment": {
            "description": "Sum of applied discounts in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_shipping_price": {
            "description": "Shipping amount in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_shipping_price_presentment": {
            "description": "Shipping amount in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_tax_price": {
            "description": "Total tax in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_tax_price_presentment": {
            "description": "Total tax in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_price": {
            "description": "Order total in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_price_presentment": {
            "description": "Order total in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the order was placed in your e-comm platform",
            "example": "2024-11-26T17:32:28Z"
          },
          "financial_status": {
            "type": "string",
            "example": "paid",
            "enum": [
              "pending",
              "paid",
              "refunded",
              "voided"
            ]
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "shipping_address": {
            "$ref": "#/components/schemas/Address"
          },
          "line_items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineItem"
            }
          }
        },
        "required": [
          "shop_order_id",
          "shop_order_number",
          "subtotal_price",
          "total_discounts_price",
          "total_shipping_price",
          "total_tax_price",
          "total_price",
          "created_at",
          "financial_status",
          "customer",
          "shipping_address",
          "line_items"
        ]
      },
      "UpdateOrder": {
        "type": "object",
        "properties": {
          "shop_order_number": {
            "type": "string",
            "description": "The Order Number as presented to the customer",
            "example": "W-94713"
          },
          "subtotal_price": {
            "description": "Order subtotal in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "subtotal_price_presentment": {
            "description": "Order subtotal in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_discounts_price": {
            "description": "Sum of applied discounts in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_discounts_price_presentment": {
            "description": "Sum of applied discounts in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_shipping_price": {
            "description": "Shipping amount in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_shipping_price_presentment": {
            "description": "Shipping amount in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_tax_price": {
            "description": "Total tax in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_tax_price_presentment": {
            "description": "Total tax in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_price": {
            "description": "Order total in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_price_presentment": {
            "description": "Order total in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "financial_status": {
            "type": "string",
            "example": "paid",
            "enum": [
              "pending",
              "paid",
              "refunded",
              "voided"
            ]
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "shipping_address": {
            "$ref": "#/components/schemas/Address"
          },
          "line_items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineItem"
            }
          }
        },
        "required": [
          "shop_order_number",
          "subtotal_price",
          "total_discounts_price",
          "total_shipping_price",
          "total_tax_price",
          "total_price",
          "financial_status",
          "customer",
          "shipping_address",
          "line_items"
        ]
      },
      "Money": {
        "type": "object",
        "properties": {
          "cents": {
            "type": "integer",
            "format": "int32",
            "example": 1299
          },
          "currency": {
            "type": "string",
            "format": "currency",
            "description": "Currency code (ISO 4217)",
            "example": "USD"
          }
        },
        "required": [
          "cents",
          "currency"
        ]
      },
      "Customer": {
        "type": "object",
        "properties": {
          "shop_customer_id": {
            "type": "string",
            "description": "Your ID for the Customer",
            "example": "7461"
          },
          "first_name": {
            "type": "string",
            "nullable": true,
            "example": "Sally"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "example": "Loo"
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "example": "sally@example.com"
          },
          "phone_number": {
            "type": "string",
            "format": "phone",
            "nullable": true,
            "example": "+13105551234"
          }
        },
        "required": [
          "shop_customer_id"
        ]
      },
      "Address": {
        "type": "object",
        "properties": {
          "address1": {
            "type": "string",
            "example": "123 Main St"
          },
          "address2": {
            "type": "string",
            "example": "Unit 50"
          },
          "province_code": {
            "type": "string",
            "example": "CA",
            "description": "Subdivision code (ISO-3166)"
          },
          "city": {
            "type": "string",
            "example": "Los Angeles"
          },
          "postal_code": {
            "type": "string",
            "example": "90210"
          },
          "country_code": {
            "type": "string",
            "example": "US",
            "description": "Alpha-2 country code (ISO-3166)"
          },
          "phone_number": {
            "type": "string",
            "format": "phone",
            "example": "+13105551234"
          }
        },
        "required": [
          "address1",
          "province_code",
          "city",
          "postal_code",
          "country_code",
          "phone_number"
        ]
      },
      "LineItem": {
        "type": "object",
        "properties": {
          "shop_line_item_id": {
            "type": "string",
            "description": "Your ID for the Line Item",
            "example": "816721"
          },
          "shop_product_id": {
            "type": "string",
            "description": "Your ID for the product",
            "example": "142"
          },
          "shop_variant_id": {
            "type": "string",
            "description": "Your ID or SKU for the variant",
            "example": "7261"
          },
          "name": {
            "type": "string",
            "description": "Name for the product and variant purchased",
            "example": "Cool T-shirt - Red"
          },
          "unit_price": {
            "description": "Item price in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_price": {
            "description": "Line item total in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "total_price_presentment": {
            "description": "Line item total in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "quantity": {
            "example": 2
          },
          "image_url": {
            "type": "string",
            "format": "url",
            "description": "URL to an image of the item",
            "example": "https://placecats.com/neo/300/200.png"
          },
          "grams": {
            "description": "Weight of the item in grams",
            "example": 24
          },
          "refunded_quantity": {
            "type": "integer",
            "format": "int32",
            "description": "Number of items refunded (for full or partial refunds)",
            "example": 1
          },
          "refunded_price": {
            "description": "Total refunded amount in shop's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          },
          "refunded_price_presentment": {
            "description": "Total refunded amount in customer's currency",
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ]
          }
        },
        "required": [
          "shop_line_item_id",
          "shop_product_id",
          "shop_variant_id",
          "name",
          "unit_price",
          "total_price",
          "quantity",
          "image_url",
          "grams"
        ]
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}