> ## Documentation Index > Fetch the complete documentation index at: https://docs.momentco.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a Bill > Creates a new bill for a customer or account. Bills represent payment requests that can be associated directly with customers or with specific accounts under customers. ## OpenAPI ````yaml POST /billing/bills openapi: 3.1.0 info: title: Moment Billing APIs version: 1.0.0 description: > # Moment Billing APIs The Moment Billing APIs provide comprehensive billing and account management capabilities for merchants to manage customers, accounts, and bills with enterprise-grade reliability and security. contact: name: Moment url: https://momentco.net email: support@momentco.net servers: - url: https://api.momentpay.net description: Production server security: - BearerAuth: [] tags: - name: Customers description: > Operations for managing customers. Customers are the primary entities in the billing system that can have accounts and bills associated with them. - name: Accounts description: > Operations for managing accounts. Accounts provide sub-organization within customers for separate balance tracking and payment management. - name: Bills description: > Operations for managing bills. Bills represent payment requests that can be associated with customers or specific accounts. - name: Webhooks description: > Webhook events that notify your application of changes in real-time. Configure webhook endpoints in your merchant dashboard to receive these notifications. externalDocs: description: Complete API Documentation url: https://docs.momentco.io/ paths: /billing/bills: post: tags: - Bills summary: Create Bill description: > Creates a new bill for a customer or account. Bills represent payment requests that can be associated directly with customers or with specific accounts under customers. operationId: createBill parameters: - $ref: '#/components/parameters/idempotency_key' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_bill_request' examples: Bill for Existing Customer ID: $ref: '#/components/examples/create_bill_existing_customer_id' Bill for Existing Customer Reference: $ref: '#/components/examples/create_bill_existing_customer_ref' Bill for New Customer: $ref: '#/components/examples/create_bill_new_customer' Bill for Existing Account ID: $ref: '#/components/examples/create_bill_existing_account_id' Bill for Existing Account Reference: $ref: '#/components/examples/create_bill_existing_account_ref' Bill for New Account and Existing Customer: $ref: >- #/components/examples/create_bill_new_account_existing_customer Bill for New Account and New Customer: $ref: '#/components/examples/create_bill_new_account_new_customer' responses: '201': $ref: '#/components/responses/bill_created' '400': $ref: '#/components/responses/bad_request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '409': $ref: '#/components/responses/bill_conflict' '500': $ref: '#/components/responses/internal_server_error' security: - BearerAuth: [] components: parameters: idempotency_key: name: Idempotency-Key in: header required: true description: > A unique key to prevent duplicate operations. Use the same key for retries to ensure idempotent behavior. **Best Practices:** - Use UUIDs or other cryptographically unique identifiers - Maintain keys for at least 24 hours for retry scenarios - Use different keys for different operations - Monitor `Idempotent-Replayed` header for cache hits schema: type: string format: uuid minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9-]+$ example: 550e8400-e29b-41d4-a716-446655440000 schemas: create_bill_request: type: object description: Request payload for creating a new bill properties: customer: description: > Customer association for the bill. Required if bill is directly associated with customer or if creating new account. oneOf: - type: string title: id description: Existing customer's unique ID pattern: ^bcus_[a-zA-Z0-9]+$ example: bcus_H4jp6KnU5cPw263v1jyz4 - type: string title: external_reference description: Existing customer's external reference maxLength: 255 pattern: ^(?!bcus_)[a-zA-Z0-9_-]+$ example: UCR1234567890 - $ref: '#/components/schemas/create_customer_inline_request' title: object account: description: > Account association for the bill. Required if bill is directly associated with account. oneOf: - type: string title: id description: Existing account's unique ID pattern: ^bacc_[a-zA-Z0-9]+$ example: bacc_H4jp6KnU5cPw263v1jyz4 - type: string title: external_reference description: Existing account's external reference maxLength: 255 pattern: ^(?!bacc_)[a-zA-Z0-9_-]+$ example: UAR1234567890 - $ref: '#/components/schemas/create_account_inline_request' title: object external_reference: $ref: '#/components/schemas/external_reference' currency: $ref: '#/components/schemas/currency' amount_due: $ref: '#/components/schemas/amount_due' bill_date: $ref: '#/components/schemas/bill_date' due_date: $ref: '#/components/schemas/due_date' metadata: $ref: '#/components/schemas/metadata_fields' required: - external_reference - currency - amount_due additionalProperties: false create_customer_inline_request: type: object description: >- Request payload for creating a customer inline while creating another entity properties: external_reference: $ref: '#/components/schemas/external_reference' name: $ref: '#/components/schemas/customer_name' email: $ref: '#/components/schemas/customer_email' phone: $ref: '#/components/schemas/customer_phone' metadata: $ref: '#/components/schemas/metadata_fields' required: - external_reference additionalProperties: false create_account_inline_request: type: object description: Request payload for creating an account inline while creating a bill properties: external_reference: $ref: '#/components/schemas/external_reference' name: $ref: '#/components/schemas/account_name' metadata: $ref: '#/components/schemas/metadata_fields' required: - external_reference additionalProperties: false external_reference: type: string description: | External reference for reconciliation or tracking purposes. Must be unique within your merchant account. maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ example: INV-2024-001 currency: title: Currency type: string description: The ISO 4217 currency code for the payment. example: ZAR amount_due: type: integer description: | Payment amount due at the time of bill creation. The value is in the smallest currency unit (e.g., cents for ZAR). minimum: 1 maximum: 99999999 example: 2000 bill_date: type: string format: date description: | The date the bill was raised in ISO 8601 format (YYYY-MM-DD). Defaults to current date if not provided. example: '2025-01-01' due_date: type: string format: date description: The due date for bill payment in ISO 8601 format (YYYY-MM-DD) example: '2025-01-31' metadata_fields: type: object description: > Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. NEW **Limitations:** - Maximum 20 keys - Key names must be strings (max 40 characters) - Values must be strings (max 500 characters) additionalProperties: type: string example: customer_id: cust_123456 order_id: ord_789012 bill: type: object description: > A bill represents a payment request that can be associated with a customer or specific account. properties: id: $ref: '#/components/schemas/bill_id' external_reference: $ref: '#/components/schemas/external_reference' customer_id: $ref: '#/components/schemas/customer_id' account_id: $ref: '#/components/schemas/account_id' status: $ref: '#/components/schemas/bill_status' currency: $ref: '#/components/schemas/currency' amount_due: $ref: '#/components/schemas/amount_due' amount_paid: $ref: '#/components/schemas/amount_paid' amount_remaining: $ref: '#/components/schemas/amount_remaining' bill_date: $ref: '#/components/schemas/bill_date' due_date: $ref: '#/components/schemas/due_date' payment_rules: $ref: '#/components/schemas/payment_rules' metadata: $ref: '#/components/schemas/metadata_fields' required: - id - external_reference - customer_id - status - currency - amount_due - amount_paid - amount_remaining additionalProperties: false problem_detail: title: Problem Detail Object type: object properties: type: type: string description: > A URI reference that identifies the problem type. This URI should provide human-readable documentation for the problem type. title: type: string description: | A short, human-readable summary of the problem type. status: type: integer description: | The HTTP status code applicable to this problem. detail: type: string description: > A human-readable explanation specific to this occurrence of the problem. instance: type: string description: > A URI reference that identifies the specific occurrence of the problem. code: type: string description: A machine-readable code that describes the specific error condition enum: - bad_request - conflict - unauthorized - missing_authorization - operation_not_allowed - resource_not_found - resource_already_exists - bill_already_voided - internal_server_error - payment_not_found example: bad_request required: - type - title - status description: | A standardized format for problem details, following RFC 9457. customer_name: type: string description: The customer's full name or business name maxLength: 255 example: John Doe customer_email: type: string format: email description: The customer's email address maxLength: 255 example: john.doe@example.com customer_phone: type: string description: The customer's phone number in E.164 format pattern: ^\+[1-9]\d{1,14}$ example: '+27123456789' account_name: type: string description: Name for the account maxLength: 255 example: Subscription Account bill_id: type: string description: Unique identifier for a bill pattern: ^bill_[a-zA-Z0-9]+$ example: bill_H4jp6KnU5cPw263v1jyz4 customer_id: type: string description: Unique identifier for a customer pattern: ^bcus_[a-zA-Z0-9]+$ example: bcus_H4jp6KnU5cPw263v1jyz4 account_id: type: string description: Unique identifier for an account pattern: ^bacc_[a-zA-Z0-9]+$ example: bacc_H4jp6KnU5cPw263v1jyz4 bill_status: type: string description: Current status of the bill enum: - unpaid - paid - voided example: unpaid amount_paid: type: integer description: > The amount that has been paid against this bill. The value is in the smallest currency unit (e.g., cents for ZAR). **Note:** If amount_paid is specified, the currency field must also be provided. minimum: 0 maximum: 99999999 example: 1500 amount_remaining: type: integer description: > The amount remaining to be paid against this bill. The value is in the smallest currency unit (e.g., cents for ZAR). **Note:** If amount_remaining is specified, the currency field must also be provided. minimum: 0 maximum: 99999999 example: 500 payment_rules: type: object description: > Payment rules associated with the entity. If not specified, the entity cannot be paid against. properties: min_amount: type: integer description: > Minimum payment amount in the smallest currency unit (e.g., cents for ZAR) minimum: 1 example: 100 max_amount: type: integer description: > Maximum payment amount in the smallest currency unit (e.g., cents for ZAR) minimum: 1 example: 1000000 underpayment_allowed: type: boolean description: Whether payments less than the full amount due are allowed example: true overpayment_allowed: type: boolean description: Whether payments greater than the amount due are allowed example: false additionalProperties: false examples: create_bill_existing_customer_id: summary: Create bill for existing customer using ID description: Bill creation using customer ID reference value: customer: bcus_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription create_bill_existing_customer_ref: summary: Create bill for existing customer using external reference description: Bill creation using customer external reference value: customer: UCR1234567890 external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription create_bill_new_customer: summary: Create bill for new customer description: Bill creation with new customer object value: customer: external_reference: UCR1234567890 name: John Doe email: john.doe@example.com external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription create_bill_existing_account_id: summary: Create bill for existing account using ID description: Bill creation using account ID reference value: account: bacc_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription create_bill_existing_account_ref: summary: Create bill for existing account using external reference description: Bill creation using account external reference value: account: UAR1234567890 external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription create_bill_new_account_existing_customer: summary: Create bill for new account under existing customer description: Bill creation with new account for existing customer value: customer: bcus_H4jp6KnU5cPw263v1jyz4 account: external_reference: UAR1234567890 name: Subscription Account external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription create_bill_new_account_new_customer: summary: Create bill for new account under new customer description: Bill creation with new account and new customer value: customer: external_reference: UCR1234567890 name: John Doe email: john.doe@example.com account: external_reference: UAR1234567890 name: Subscription Account external_reference: UBR1234567890 currency: ZAR amount_due: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' metadata: invoice_period: January 2025 service_type: subscription responses: bill_created: description: Bill created successfully content: application/json: schema: $ref: '#/components/schemas/bill' examples: Bill for Existing Customer ID: summary: Bill created for existing customer by ID value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription Bill for Existing Customer Reference: summary: Bill created for existing customer by reference value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription Bill for New Customer: summary: Bill created with a new inline customer value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription Bill for Existing Account ID: summary: Bill created for existing account by ID value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription Bill for Existing Account Reference: summary: Bill created for existing account by reference value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription Bill for New Account and Existing Customer: summary: Bill created with new account for existing customer value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription Bill for New Account and New Customer: summary: Bill created with new account and new customer value: id: bill_H4jp6KnU5cPw263v1jyz4 external_reference: UBR1234567890 customer_id: bcus_H4jp6KnU5cPw263v1jyz4 account_id: bacc_H4jp6KnU5cPw263v1jyz4 status: unpaid currency: ZAR amount_due: 2000 amount_paid: 0 amount_remaining: 2000 bill_date: '2025-01-01' due_date: '2025-01-31' payment_rules: min_amount: 100 max_amount: 2000 underpayment_allowed: true overpayment_allowed: false metadata: invoice_period: January 2025 service_type: subscription headers: Request-Id: $ref: '#/components/headers/request_id' Idempotent-Replayed: description: > Indicates whether this response is a replay of a previous request due to idempotency. When `true`, the response is being returned from cache based on the Idempotency-Key provided in the request. schema: type: boolean example: false Location: description: URL of the created resource schema: type: string format: uri example: /billing/bills/bill_H4jp6KnU5cPw263v1jyz4 bad_request: description: Bad Request - Invalid request parameters or malformed request content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Invalid Currency: summary: Invalid currency code value: type: https://docs.momentco.io/errors/bad-request title: Bad Request status: 400 detail: The currency field must be a valid ISO 4217 currency code. instance: /billing/customers code: bad_request Invalid Amount: summary: Invalid amount value: type: https://docs.momentco.io/errors/bad-request title: Bad Request status: 400 detail: The amount field must be a positive integer. instance: /billing/bills code: bad_request headers: Request-Id: $ref: '#/components/headers/request_id' unauthorized: description: Unauthorized - Invalid or missing authentication credentials content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Invalid API Key: summary: Invalid API key value: type: https://docs.momentco.io/errors/unauthorized title: Unauthorized status: 401 detail: The API key provided is invalid. instance: /billing/customers code: unauthorized Missing Authorization: summary: Missing authorization header value: type: https://docs.momentco.io/errors/unauthorized title: Unauthorized status: 401 detail: Authorization header is required. instance: /billing/customers code: missing_authorization headers: Request-Id: $ref: '#/components/headers/request_id' forbidden: description: Forbidden - Operation not allowed for the authenticated user content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Operation Not Allowed: summary: Operation not allowed value: type: https://docs.momentco.io/errors/forbidden title: Forbidden status: 403 detail: Merchant is not allowed to perform this action. instance: /billing/customers code: operation_not_allowed headers: Request-Id: $ref: '#/components/headers/request_id' bill_conflict: description: Conflict - Resource state conflict or duplicate resource headers: Request-Id: $ref: '#/components/headers/request_id' content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Bill Already Exists: summary: Bill already exists value: type: https://docs.momentco.io/errors/conflict title: Conflict status: 409 detail: A bill with the same external reference already exists. instance: /billing/bills code: resource_already_exists internal_server_error: description: Internal Server Error - An unexpected error occurred content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Internal Server Error: summary: Internal server error value: type: https://docs.momentco.io/errors/internal-server-error title: Internal Server Error status: 500 detail: An unexpected error occurred. Please try again later. instance: /billing/customers code: internal_server_error headers: Request-Id: $ref: '#/components/headers/request_id' headers: request_id: description: > A unique identifier for the request, used for tracing and debugging purposes. This `Request-Id` is included in every response to enable request tracing across multiple services or systems. It helps correlate logs and track the flow of requests through distributed systems. The value is typically a universally unique identifier (UUID) to ensure uniqueness across requests. schema: type: string examples: - 63efe730-f599-40a5-afb7-9dda5fc31773 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Authentication using Bearer tokens. Include your API key in the Authorization header. **Key Types:** - **Test Keys**: `sk_test_*` for development and testing - **Live Keys**: `sk_*` for production environments - **Public Keys**: `pk_test_*` or `pk_*` for client-side operations > 📩 **Need access?** [Contact Support](/documentation/support) to request your API keys. **Usage:** ```http Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc ``` ````