Open API

List all reference-data collection names.

200 response

{
  "schemaVersion": "2026.07.1",
  "collections": [
    "countries", "currencies", "carriers", "product-categories",
    "destination-continent-categories", "goods-value-categories",
    "certificate-types", "endorse-scenes", "cancel-reasons",
    "claim-types", "policy-statuses", "claim-customer-statuses"
  ]
}

Get enum items for a collection. Supports If-None-Match; returns 304 when unchanged.

Path parameters

200 example — cancel-reasons

{
  "schemaVersion": "2026.07.1",
  "collection": "cancel-reasons",
  "items": [
    { "code": "merchantRefund", "name": "Merchant refund before shipment" },
    { "code": "duplicatePolicy", "name": "Duplicate policy" },
    { "code": "customerWithdraw", "name": "Customer withdrawal" },
    { "code": "other", "name": "Other" }
  ]
}

Calculate premium from insured amount; does not create a policy. Same pricing as apply: destination-country catalog rate + markup, matched to a price tier.

Quote does not require lineItems, orderPlacedAt, estimatedArrivalDate, buyer, or trackingNumber. It does not enforce the 24-hour order window.

merchantShop and metadata may be included but are ignored until apply.

Request body

Example request

{
  "externalReference": "ORD-1001",
  "risk": {
    "trackingNumber": "1Z999AA10123456784",
    "carrierCode": "17",
    "carrierName": "UPS",
    "insuredAmount": { "amount": "180.00", "currencyCode": "USD" },
    "destination": {
      "countryCode": "US", "city": "Los Angeles",
      "provinceCode": "CA", "addressLine": "123 Main St"
    },
    "departure": {
      "countryCode": "CN", "city": "Shenzhen",
      "addressLine": "Factory Zone A"
    }
  }
}

200 response

{
  "externalReference": "ORD-1001",
  "insuredAmount": { "amount": "180.00", "currencyCode": "USD" },
  "premiumAmount": { "amount": "2.99", "currencyCode": "USD" },
  "quoteExpiresInSeconds": 60
}

Bind a policy on the Gooval platform after shipment. Returns policyNo immediately. Reinsurance (if the catalog product is not self-retained) is submitted asynchronously and is never exposed to merchants.

Requires Idempotency-Key header.

Key fields

Omitted merchantShop / metadata fields are not returned later. Endorsement and cancel do not change them.

Example request

{
  "externalReference": "ORD-1002",
  "orderPlacedAt": "2026-08-20T09:15:00Z",
  "merchantShop": { "id": "shop_8821", "name": "Acme US" },
  "metadata": { "channel": "tiktok", "settlementCode": "NA-01" },
  "risk": {
    "trackingNumber": "1Z999AA10123456784",
    "carrierCode": "17",
    "carrierName": "UPS",
    "insuredAmount": { "amount": "180.00", "currencyCode": "USD" },
    "estimatedArrivalDate": "2026-08-25",
    "destination": {
      "countryCode": "US", "city": "Los Angeles",
      "provinceCode": "CA", "addressLine": "123 Main St, Los Angeles, CA"
    },
    "departure": {
      "countryCode": "CN", "city": "Shenzhen",
      "addressLine": "Factory Zone A"
    },
    "lineItems": [{
      "itemId": "LINE-001", "sku": "TEE-BLU-M", "name": "Blue Tee",
      "category": "apparel",
      "quantity": 2,
      "unitPrice": { "amount": "50.00", "currencyCode": "USD" },
      "imageUrl": "https://cdn.merchant.com/tee.jpg"
    }]
  },
  "buyer": { "name": "Jane Doe", "email": "buyer@example.com" }
}

lineItems rules (required)

• Each line requires name, category (from reference-data/product-categories), quantity (≥1), unitPrice, and at least one of sku or itemId
• Sum of unitPrice × quantity must equal risk.insuredAmount (same currency, ±0.01 rounding)
• Optional imageUrl must be https. Lines are returned in claim lookup as orderLineItems

Omitting lineItems returns 400 field_required. Missing or unknown category returns field_required / invalid_enum. Legacy policies bound before this change still fall back to a single virtual line at claim lookup.

If trackingNumber is omitted at apply, reinsurance waits until a later changeShipment supplies it. GET .../document returns a Gooval application confirmation (not a reinsurer policy).

If externalReference already has an active policy, apply returns 200 with error: duplicate_external_reference — use GET /policies?externalReference= or POST .../cancel before re-applying.

200 success (merchant-visible)

{
  "policyNo": "P2026070612345678",
  "externalReference": "ORD-1002",
  "status": "active",
  "premium": { "amount": "2.99", "currencyCode": "USD" },
  "insuredAmount": { "amount": "180.00", "currencyCode": "USD" },
  "merchantShop": { "id": "shop_8821", "name": "Acme US" },
  "metadata": { "channel": "tiktok", "settlementCode": "NA-01" }
}

spNumber is never returned to merchants.

200 duplicate apply

{
  "error": "duplicate_external_reference",
  "message": "externalReference already has an active policy",
  "field": "externalReference"
}

Get a presigned URL to upload policy attachments before apply.

1. POST /open/v1/policies/attachments/upload-url with { "contentType", "contentLength", "type"?, "fileName"? }
2. PUT the file to the returned uploadUrl (include the same Content-Type)
3. Pass attachmentKey on apply

Allowed types: invoice, packingList, productPhoto, other. Files: PDF / JPEG / PNG / WebP, 1 byte–5 MB, max 10 per apply. This route is not 24h-idempotent (presigned URLs expire in 900 seconds).

"attachments": [
  {
    "attachmentKey": "open-policy-attachments/{storeNumber}/{uuid}.pdf",
    "type": "invoice",
    "fileName": "invoice.pdf"
  }
]

GET /policies/{policyNo} echoes orderPlacedAt and attachments (keys only; no download URL). Attachments are not sent to the reinsurer.

Query parameters

200 response

{
  "items": [{
    "policyNo": "P2026070612345678",
    "externalReference": "ORD-1002",
    "status": "active",
    "orderName": "#1002",
    "premium": { "amount": "2.99", "currencyCode": "USD" },
    "createdAt": "2026-07-06T06:00:00+00:00"
  }],
  "nextCursor": "eyJ..."
}

Get a single policy including orderPlacedAt, attachment keys (no download URLs), and merchantShop / metadata when set at apply.

Get a pre-signed URL for the Gooval application confirmation PDF (documentType: confirmation). This is not an insurance policy.

Use ?lang=zh or ?lang=en (locale / language also accepted; default en). Reinsurer policy PDFs are not available on the Open API (source=policy returns 400 invalid_document_source).

{ "downloadUrl": "https://...", "expiresIn": 900, "documentType": "confirmation" }

Endorse a policy. Gooval applies the change immediately. If the policy is already submitted to a reinsurer, Ping An intelligentEndorse (edrSceneCode: ["900013"]) runs asynchronously and does not fail this request.

Request body

endorseScene values

Example request

{
  "endorseScene": "changeShipment",
  "changes": {
    "trackingNumber": "1Z999AA10987654321",
    "carrierCode": "17",
    "carrierName": "UPS",
    "estimatedArrivalDate": "2026-08-28"
  },
  "reason": "Carrier re-issued tracking label",
  "remark": "Original label voided"
}

Cancel a policy. Gooval cancels immediately only when the policy has no tracking number. If the policy is already submitted to a reinsurer, Ping An intelligentEndorse (edrSceneCode: ["00006"]) runs asynchronously and does not fail this request.

Request body

{
  "cancelReasonCode": "merchantRefund",
  "cancelReason": "Order refunded before shipment",
  "remark": "Customer cancelled order ORD-1001"
}

200 response status is cancelled.

Returns 409 cancel_blocked_by_shipment when risk.trackingNumber is present, and 409 cancel_blocked_by_claim when the policy has a completed claim or an incomplete claim application.

Query parameters

Event types: policy.insured · policy.failed · policy.endorsed · policy.cancelled · claim.submitted · claim.status_changed · claim.completed