# Points

> Points API - Saudi Arabia's unified loyalty rewards platform

## Docs

- [Toggle integration active state](https://docs.papp.sa/api-reference/integration/toggle-integration-active-state.md): Mirrors the merchant's external-platform toggle (Matajer's "ربط بوينتس" switch today, any other channel tomorrow) into our DB. Flips the `integration_active` flag on the API key that authenticated the request — driving the green/red dot on our `/merchants` listing and any business logic that needs t…
- [Authorize an order](https://docs.papp.sa/api-reference/orders/authorize-an-order.md): Updates the order status to `authorized`, if allowed.
- [Begin checkout for a replacing order](https://docs.papp.sa/api-reference/orders/begin-checkout-for-a-replacing-order.md): Starts a checkout session for a replacing (redeem + pay) order using the merchant's public key. This endpoint does **not** require the `x-api-key` header — the public key in the path authenticates the call. When `phone_number` is provided but no matching customer exists, the returned `checkout_url`…
- [Cancel an order](https://docs.papp.sa/api-reference/orders/cancel-an-order.md): Cancels an order and fires the `cancelled` webhook. If `reason` is omitted, the server stores the default `"Order cancelled via API"` and echoes it in the webhook payload.
- [Capture an order](https://docs.papp.sa/api-reference/orders/capture-an-order.md): Updates the order status to `captured`, if allowed.
- [Complete an order checkout](https://docs.papp.sa/api-reference/orders/complete-an-order-checkout.md): Marks a replacing order as fully paid and records the payment method. Only replacing orders that are not already completed, refunded, or cancelled may be completed.
- [Create a product-rating earning order](https://docs.papp.sa/api-reference/orders/create-a-product-rating-earning-order.md): Awards points to a customer for submitting a rating of a specific product. The points amount is configured by the merchant in the Points dashboard — the request body does not carry the points value. The request is serialized inside a distributed lock scoped to the authenticated merchant, and `review…
- [Create a store-rating earning order](https://docs.papp.sa/api-reference/orders/create-a-store-rating-earning-order.md): Awards points to a customer for submitting a rating of the merchant's store. The points amount is configured by the merchant in the Points dashboard — the request body does not carry the points value. The request is serialized inside a distributed lock scoped to the authenticated merchant, and `revi…
- [Create an earning order](https://docs.papp.sa/api-reference/orders/create-an-earning-order.md): Creates an earning order (points awarded on a completed off-platform purchase). The request is serialized inside a distributed lock scoped to the authenticated merchant to reduce concurrent processing conflicts.
- [Refund an order](https://docs.papp.sa/api-reference/orders/refund-an-order.md): Issues a full or partial refund and returns points to the customer. When `amount` is omitted, the full captured amount is refunded. Rules (refund window, order state) are enforced by the backend `RefundService`.
- [Retrieve an order](https://docs.papp.sa/api-reference/orders/retrieve-an-order.md): Fetch a single order by its UUID for the authenticated merchant.
- [Update shipping status](https://docs.papp.sa/api-reference/orders/update-shipping-status.md): Updates the shipping/fulfilment status of an order and fires the `shipping_status_updated` webhook. This is a separate lifecycle from the financial `order_status`.
- [Create a webhook](https://docs.papp.sa/api-reference/webhooks/create-a-webhook.md): Registers a new webhook for the authenticated merchant.
- [Delete a webhook](https://docs.papp.sa/api-reference/webhooks/delete-a-webhook.md): Deletes a webhook for the authenticated merchant.
- [List webhooks](https://docs.papp.sa/api-reference/webhooks/list-webhooks.md): Returns a paginated list of webhooks for the authenticated merchant.
- [Partially update a webhook](https://docs.papp.sa/api-reference/webhooks/partially-update-a-webhook.md): Provides a partial update for a webhook. Only supplied fields are changed.
- [Retrieve a webhook](https://docs.papp.sa/api-reference/webhooks/retrieve-a-webhook.md): Fetch a single webhook by UUID for the authenticated merchant.
- [Update a webhook](https://docs.papp.sa/api-reference/webhooks/update-a-webhook.md): Updates the name and/or URL of a webhook. All provided fields replace existing values.
- [API Keys](https://docs.papp.sa/authentication/api-keys.md): Public and Private keys — what they do and how to use them
- [IP Whitelisting](https://docs.papp.sa/authentication/ip-whitelisting.md): Restrict which IP addresses can call the Points API on behalf of your merchant
- [Security Best Practices](https://docs.papp.sa/authentication/security.md): How to integrate with Points safely
- [Matajer](https://docs.papp.sa/e-commerce-platforms/matajer.md)
- [Checkout Flow](https://docs.papp.sa/integration/checkout-flow.md): End-to-end redeem + earn checkout integration
- [Earning Methods](https://docs.papp.sa/integration/earning-methods.md): Three ways customers can earn points on your platform
- [Order Lifecycle & Statuses](https://docs.papp.sa/integration/order-lifecycle.md): State machine, status enums, and shipping labels for Points orders
- [Refunds & Cancellations](https://docs.papp.sa/integration/refunds-cancellations.md): Rules, windows, and partial refund behaviour
- [F.A.Q.](https://docs.papp.sa/introduction/faq.md): Frequently asked questions about Points
- [Quick start](https://docs.papp.sa/introduction/quickstart.md): Make your first Points API call in under 10 minutes
- [Technical Requirements](https://docs.papp.sa/introduction/technical-requirements.md): System requirements for Points integration
- [What is Points ?](https://docs.papp.sa/introduction/what-is-points.md): Saudi Arabia's unified loyalty rewards platform
- [PHP SDK](https://docs.papp.sa/sdk/php-sdk.md): Official Points PHP SDK for backend integrations
- [Testing Credentials](https://docs.papp.sa/testing/credentials.md): Sandbox environment and test identities
- [Go-Live Checklist](https://docs.papp.sa/testing/go-live-checklist.md): Final checks before flipping production traffic
- [Webhook Events](https://docs.papp.sa/webhooks/events.md): Full catalogue of events Points delivers to your webhook endpoints
- [Webhook Management](https://docs.papp.sa/webhooks/management.md): Create, list, update, and delete webhook endpoints
- [Webhooks Overview](https://docs.papp.sa/webhooks/overview.md): Real-time order notifications — how they fire, how to verify them, how to handle them safely
- [Widgets](https://docs.papp.sa/widgets/overview.md): Embed Points promotional messaging on product and checkout pages
- [Widget Playground](https://docs.papp.sa/widgets/widget-playground.md): Interactive test page for all Points widget types

## OpenAPI Specs

- [points-api-v1](https://docs.papp.sa/openapi/points-api-v1.yaml)
- [openapi](https://docs.papp.sa/api-reference/openapi.json)