# Cheqi API Cheqi provides APIs for creating receipts and reading receipts for customers Version: v1 ## Servers Production ``` https://api.cheqi.io ``` Sandbox ``` https://sandbox.api.cheqi.io ``` ## Security ### cheqi_oauth OAuth 2.0 for client applications acting on behalf of a company and/or user. Use the authorization_code flow for user-authorized access and the client_credentials flow for trusted partner bootstrap. Type: oauth2 ### cheqi_api_key Company API key. Send it as `Authorization: Bearer sk_...`. Type: http Scheme: bearer ## Download OpenAPI description [Cheqi API](https://docs.cheqi.io/_bundle/apis/api-docs.yaml) ## Store Management Endpoints for managing lightweight store/location records under a company. Stores are not child companies and do not create a separate Cheqi company identity. ### Get store location - [GET /company/{companyId}/stores/{storeId}](https://docs.cheqi.io/apis/api-docs/store-management/getstore.md): Gets a specific lightweight store/location record under the specified company. OAuth client applications require the read_stores scope. ### Update store location - [PUT /company/{companyId}/stores/{storeId}](https://docs.cheqi.io/apis/api-docs/store-management/updatestore.md): Updates a lightweight store/location record under the specified company. OAuth client applications require the write_stores scope. ### List store locations - [GET /company/{companyId}/stores](https://docs.cheqi.io/apis/api-docs/store-management/getstores.md): Lists lightweight store/location records for the specified company. This does not list child companies. OAuth client applications require the read_stores scope. ### Create store location - [POST /company/{companyId}/stores](https://docs.cheqi.io/apis/api-docs/store-management/createstore.md): Creates a lightweight store/location record under the specified company. Use child companies instead when the branch or franchisee needs its own Cheqi company identity, tax details, permissions, or reporting boundary. OAuth client applications require the write_stores scope. ### Deactivate store location - [PATCH /company/{companyId}/stores/{storeId}/deactivate](https://docs.cheqi.io/apis/api-docs/store-management/deactivatestore.md): Deactivates a store/location without deleting its history. OAuth client applications require the write_stores scope. ### Activate store location - [PATCH /company/{companyId}/stores/{storeId}/activate](https://docs.cheqi.io/apis/api-docs/store-management/activatestore.md): Reactivates a previously deactivated store/location. OAuth client applications require the write_stores scope. ## Client Application Management Endpoints for managing OAuth2 client applications, including registration, secret management, and public key configuration ### Rotate webhook signing secret - [POST /client-application/{id}/webhook/rotate-secret](https://docs.cheqi.io/apis/api-docs/client-application-management/rotatewebhooksecret.md): Generates a new signing secret for all webhook subscriptions owned by this client application. Only the owning company or admin users can rotate the secret. The old secret will be invalidated immediately. Accessible for: User, Company ### Get client application public key - [GET /client-application/{clientApplicationId}/public-key](https://docs.cheqi.io/apis/api-docs/client-application-management/getclientapplicationpublickey.md): Retrieves the public key information for a client application, including the key data, algorithm, and upload timestamp. This key is used to verify signatures from the client application. Accessible for: Company, User ### Upload client application public key - [POST /client-application/{clientApplicationId}/public-key](https://docs.cheqi.io/apis/api-docs/client-application-management/uploadclientapplicationpublickey.md): Uploads a public key for the client application. This key is used to verify signatures from the client application when it signs receipts or other data. Can be called by company admins or using company API key authentication. Accessible for: Company, User ### Get authorized resources - [GET /client-application/authorized-resources](https://docs.cheqi.io/apis/api-docs/client-application-management/getauthorizedresources.md): Returns all resources the client application is authorized to access, organized hierarchically by companies, payment accounts, cards, and emails. Accessible for: Client Application ## Credit Note Management Endpoints for creating, managing, and retrieving credit notes (refund receipts) ### Generate credit note template - [POST /credit-note/template](https://docs.cheqi.io/apis/api-docs/credit-note-management/createreceipttemplate_1.md): Generates a UBL-compliant credit note template without customer personal data. The template can be used by the SDK to inject customer information and encrypt the credit note. Requires write_receipts OAuth scope. Accessible for: Company, Client Application ### Initiate credit note request - [POST /credit-note/initiate](https://docs.cheqi.io/apis/api-docs/credit-note-management/createcreditnote.md): Initiates a credit note (refund) request from a customer's device. The request is encrypted and queued for processing. Accessible for: User ### Submit encrypted credit note - [POST /credit-note/encrypted](https://docs.cheqi.io/apis/api-docs/credit-note-management/submitencryptedreceipt_1.md): Submits an encrypted credit note to the queue for delivery to customer devices. The credit note is encrypted with customer device keys for end-to-end privacy. Accessible for: Company, Client Application ### Get all outstanding credit note initiation requests - [GET /credit-note](https://docs.cheqi.io/apis/api-docs/credit-note-management/getallcreditnotes.md): Retrieves all outstanding credit note initiation requests for the authenticated company or client application. These are customer-initiated refund requests that are pending processing. Accessible for: Company, Client Application ## Company Management Public company endpoints for trusted partner provisioning and parent-child company hierarchy management ### Update company receipt delivery for one device - [PUT /company/{id}/receipt-delivery/devices/{deviceId}](https://docs.cheqi.io/apis/api-docs/company-management/updatereceiptdeliverydevice.md): Enables or disables company receipt delivery for one of the authenticated user's devices. Accessible for: User ### Create child company - [POST /company/{parentId}/children](https://docs.cheqi.io/apis/api-docs/company-management/addchildcompany.md): Creates a child company under an existing parent company. Use this when a branch, franchisee, or location should be modeled as its own Cheqi company with its own company identity. This is different from store management, which creates lightweight store/location records under a single company. The authenticated user must be an admin of the parent company. Accessible for: User ### Get company receipt delivery devices for the current user - [GET /company/{id}/receipt-delivery/devices](https://docs.cheqi.io/apis/api-docs/company-management/getreceiptdeliverydevices.md): Returns the authenticated user's active devices and whether each one is enabled to receive company receipts for the specified company. Accessible for: User ### getIdentifierRequirements - [GET /company/identifier-requirements](https://docs.cheqi.io/apis/api-docs/company-management/getidentifierrequirements.md): Accessible for: User ## Recipient Management Endpoints for resolving and matching receipt recipients ### Resolve receipt recipient - [POST /recipient/resolve](https://docs.cheqi.io/apis/api-docs/recipient-management/matchcustomer.md): Resolves and matches a receipt recipient based on the provided identification details (email, phone number, IBAN, or card number). Returns the matched recipient's details if found, enabling receipt delivery to the correct user. Accessible for: Company, Client Application ## Receipt Management Endpoints for creating and managing purchase receipts with end-to-end encryption ### Generate receipt template - [POST /receipt/template](https://docs.cheqi.io/apis/api-docs/receipt-management/createreceipttemplate.md): Generates a receipt template without matched customer context. The response contains the requested receipt representations, such as CHEQI JSON and optional UBL XML, plus VAT metadata for the transaction. Requires write_receipts OAuth scope. Accessible for: Company, Client Application ### Acknowledge queued receipts - [POST /receipt/queue/acknowledge/received](https://docs.cheqi.io/apis/api-docs/receipt-management/acknowledgequeuedreceipts.md): Acknowledges successfully processed queued receipts for the authenticated company or client application. Requires read_receipts OAuth scope. Accessible for: Client Application, Company ### Acknowledge permanent failure for queued receipts - [POST /receipt/queue/acknowledge/failed-permanent](https://docs.cheqi.io/apis/api-docs/receipt-management/acknowledgequeuedreceiptspermanentfailure.md): Marks queued receipts as permanently failed for the authenticated company or client application. Requires read_receipts OAuth scope. Accessible for: Client Application, Company ### Submit encrypted receipt - [POST /receipt/encrypted](https://docs.cheqi.io/apis/api-docs/receipt-management/submitencryptedreceipt.md): Submits recipient-specific encrypted purchase receipts to the queue for delivery. Each encryptedReceipt value must be the ciphertext of a plaintext envelope assembled locally from the receipt template plus customer context envelope for that recipient. Requires write_receipts OAuth scope. Accessible for: Company, Client Application ### Send receipt via email - [POST /receipt/email](https://docs.cheqi.io/apis/api-docs/receipt-management/submitreceiptwithemail.md): Sends a purchase receipt directly to a customer via email. The receipt is delivered as a PDF attachment. Requires write_receipts OAuth scope. Accessible for: Company, Client Application ### Get queued encrypted receipts - [GET /receipt/queue](https://docs.cheqi.io/apis/api-docs/receipt-management/getqueuedreceipts.md): Returns pending encrypted receipts for the authenticated company or client application. Receipts remain in the queue until they are explicitly acknowledged or marked as permanently failed. Requires read_receipts OAuth scope. Accessible for: Client Application, Company ## Webhook Management Endpoints for managing webhook subscriptions to receive real-time event notifications ### Create webhook subscription - [POST /webhook/subscription](https://docs.cheqi.io/apis/api-docs/webhook-management/handlewebhook.md): Creates a webhook subscription to receive real-time notifications for receipt and credit note events. The webhook URL will be called when events occur for the authenticated company or client application. Accessible for: Company, Client Application