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. All amount fields use integer minor units — see Money.

Request body

Example request

{
  "externalReference": "ORD-1001",
  "risk": {
    "trackingNumber": "1Z999AA10123456784",
    "carrierCode": "17",
    "carrierName": "UPS",
    "insuredAmount": { "amount": 18000, "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": 18000, "currencyCode": "USD" },
  "premiumAmount": { "amount": 299, "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. Monetary amount fields use integer minor units — see Money.

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": 10000, "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": 5000, "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, minor units)
• 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 or syncShipments supplies it. Apply does not take a shipment list.

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": 299, "currencyCode": "USD" },
  "insuredAmount": { "amount": 10000, "currencyCode": "USD" },
  "merchantShop": { "id": "shop_8821", "name": "Acme US" },
  "metadata": { "channel": "tiktok", "settlementCode": "NA-01" }
}

spNumber is never returned to merchants.

200 duplicate apply

Same shape as other errors: includes requestId (and response header X-Request-Id). Use GET /policies?externalReference= to fetch the existing policy, or cancel before re-applying.

{
  "error": "duplicate_external_reference",
  "message": "externalReference already has an active policy",
  "field": "externalReference",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

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": 299, "currencyCode": "USD" },
    "createdAt": "2026-07-06T06:00:00+00:00"
  }],
  "nextCursor": "eyJ..."
}

Get a single policy including orderPlacedAt, risk.shipments when using multi-shipment endorse (tracking number, carrier, line items, insured amount per shipment), attachment keys (no download URLs), and merchantShop / metadata when set at apply. Reinsurer policy numbers are not included.

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

The PDF is rendered from Gooval's HTML confirmation template (configured by Gooval Admin; en and zh layouts). Until a custom template is saved, the built-in default layout is used. Template updates change the PDF cache key — the next download regenerates the file.

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"
}

Register or update multiple tracking numbers on one platform policy. Apply does not accept a shipment list — omit risk.trackingNumber at apply when the order has not shipped, then call endorse with endorseScene: syncShipments as shipments go out.

Rules

• Each call sends the complete shipment list (1–10 shipments), not only new tracking numbers. A tracking number omitted from a later call is treated as removed.
• Each shipment requires trackingNumber, carrierCode or carrierName, and lineItems (same line rules as apply; shipment insured amount in minor units).
• Optional per shipment: estimatedArrivalDate, sailDepartureDate.
• One platform policyNo. Reinsurance is submitted once per tracking number and is not exposed on this API. Unchanged tracking numbers are not resubmitted; new numbers are applied at the reinsurer; removed numbers that were already submitted are cancelled at the reinsurer while the platform policy stays active.
• Policies that already have a single risk.trackingNumber cannot use syncShipments (409 single_tracking_policy). After the first syncShipments, changeShipment returns 400 use_sync_shipments.

Example request

{
  "endorseScene": "syncShipments",
  "changes": {
    "shipments": [
      {
        "trackingNumber": "1Z999AA10123456784",
        "carrierCode": "17",
        "carrierName": "UPS",
        "insuredAmount": { "amount": 9000, "currencyCode": "USD" },
        "estimatedArrivalDate": "2026-08-25",
        "lineItems": [{
          "itemId": "LINE-001",
          "sku": "TEE-BLU-M",
          "name": "Blue Tee",
          "category": "apparel",
          "quantity": 1,
          "unitPrice": { "amount": 9000, "currencyCode": "USD" }
        }]
      },
      {
        "trackingNumber": "1Z999AA10987654321",
        "carrierCode": "17",
        "insuredAmount": { "amount": 9000, "currencyCode": "USD" },
        "lineItems": [{
          "itemId": "LINE-002",
          "name": "Red Tee",
          "category": "apparel",
          "quantity": 1,
          "unitPrice": { "amount": 9000, "currencyCode": "USD" }
        }]
      }
    ]
  },
  "reason": "Order split into two packages"
}

GET /policies/{policyNo} echoes risk.shipments (tracking number, carrier, line items, insured amount). Reinsurer policy numbers are not included.

Whole-policy cancel (POST .../cancel) is only allowed before any tracking number exists. Removing one shipment in syncShipments is not a policy cancel. See Cancel.

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 any tracking number is present (including one shipment on a multi-shipment policy). Whole-policy cancel is only allowed before any tracking number exists. Removing a shipment via syncShipments is not a policy cancel.

Returns 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