Policies

A policy is the cover a customer bought for one unit of one item. Creating a policy activates the cover and emails the customer their policy documents.

The policy object

{
  "id": "pol_01JD7QB2N4R6T8V0X2Z4B6D8F0",
  "object": "policy",
  "status": "active",
  "offer": "off_01JD7Q8S4M5W2X3Y4Z6A7B8C9D",
  "merchant": "mer_01JD7Z4K2Q8V6N3R5T7W9Y1A3C",
  "order_reference": "100482",
  "item": {
    "reference": "SKU-CBX-48",
    "name": "City Bike Explorer",
    "category": "bikes",
    "price": 499000
  },
  "plan": { "id": "plan_36m", "label": "3 years", "term_months": 36 },
  "premium": 29900,
  "currency": "NOK",
  "starts_at": "2026-10-23T13:45:51Z",
  "ends_at": "2029-10-23T13:45:51Z",
  "cancelled_at": null,
  "cancellation_reason": null,
  "documents": { "certificate_url": "https://getphew.com/p/pol_01JD7QB2.../certificate" },
  "created_at": "2026-10-23T13:45:51Z",
  "metadata": {}
}

status enum

active, cancelled or expired. A policy expires automatically at ends_at.

premium integer

The premium paid, in minor units, as quoted in the offer.

starts_at timestamp

When cover begins: the moment the policy is created.

ends_at timestamp

When cover ends.

documents.certificate_url string

The customer’s policy certificate. The link requires the customer to verify their email before it opens.

Create policies

POST api.getphew.com/v1/policies policies:write

Call this when the order is paid. It creates one policy per covered unit and returns them as a list. Requires an Idempotency-Key.

Request body

offer string required

The offer ID. Must not be expired.

order_reference string required

Your order ID, as the customer sees it.

items array required

The covered items and the plan chosen for each.

reference string required

An item reference from the offer.

plan string required

A plan ID offered for that item.

quantity integer

Units to cover. Defaults to 1; at most the quantity in the offer.

customer object required

name string required

Full name.

email string required

Where the policy documents are sent.

locale string

BCP 47 locale for emails, for example nb-NO.

phone string

E.164 format, for claims contact.

payment object

Only for split settlement.

reference string required

Your payment or capture ID.

metadata object

Up to 20 key-value string pairs.

Response 201

{
  "object": "list",
  "data": [{ "id": "pol_01JD7QB2N4R6T8V0X2Z4B6D8F0", "object": "policy", "status": "active" }],
  "has_more": false
}

Note

Only create policies after the payment has succeeded. If the customer pays later (for example by invoice), create the policy when the order is confirmed, and cancel it if the payment is never made.

Retrieve a policy

GET api.getphew.com/v1/policies/{id} policies:read

List policies

GET api.getphew.com/v1/policies policies:read

Query parameters

order_reference string

Only policies for this order.

status enum

active, cancelled or expired.

created[gte], created[lt] timestamp

Filter by creation time.

limit, starting_after integer, string

Pagination.

Cancel a policy

POST api.getphew.com/v1/policies/{id}/cancel policies:cancel

Cancel when the covered item is returned, the order is cancelled, or the customer withdraws. Phew calculates the refund: the full premium within the cooling-off period, otherwise pro rata.

Request body

reason enum required

item_returned, order_cancelled, withdrawal (the customer used their right of withdrawal) or merchant_request.

Response 200

{
  "id": "pol_01JD7QB2N4R6T8V0X2Z4B6D8F0",
  "object": "policy",
  "status": "cancelled",
  "cancelled_at": "2026-10-30T09:12:44Z",
  "cancellation_reason": "item_returned",
  "refund": { "amount": 29900, "currency": "NOK" }
}

Cancelling a policy with an open claim returns 409 invalid_state.