{"openapi":"3.1.0","info":{"title":"POST /api/v1/credit-memos","version":"1.0.0","description":"Create credit memo"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit-memos":{"post":{"tags":["credit-memos"],"summary":"Create credit memo","description":"Create a new credit memo in draft status.","operationId":"create_credit_memo_api_v1_credit_memos_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditMemoCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditMemoResponse"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"detail":"Invalid request parameters"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"detail":"Not authenticated"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"detail":"Not enough permissions"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"detail":"Resource not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CreditMemoApplicationResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Application record ID"},"credit_memo_id":{"type":"string","title":"Credit Memo Id","description":"Source credit memo ID"},"invoice_id":{"type":"string","title":"Invoice Id","description":"Invoice the credit was applied to"},"amount_applied":{"type":"integer","title":"Amount Applied","description":"Amount applied in cents"},"amount_applied_dollars":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Applied Dollars","description":"Amount applied in dollars"},"applied_at":{"type":"string","format":"date-time","title":"Applied At","description":"When the credit was applied"},"applied_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Applied By User Id","description":"User who applied the credit"}},"type":"object","required":["id","credit_memo_id","invoice_id","amount_applied","amount_applied_dollars","applied_at"],"title":"CreditMemoApplicationResponse","description":"Response schema for a credit memo application."},"CreditMemoCreate":{"properties":{"customer_id":{"type":"string","title":"Customer Id","description":"Customer receiving the credit"},"amount_cents":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount Cents","description":"Credit amount in cents"},"reason":{"$ref":"#/components/schemas/CreditMemoReasonEnum","description":"Reason for the credit memo","default":"other"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the credit"},"invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Id","description":"Original invoice being credited (optional)"},"issue_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Issue Date","description":"Issue date (defaults to today)"},"line_items":{"anyOf":[{"items":{"$ref":"#/components/schemas/CreditMemoLineItem"},"type":"array"},{"type":"null"}],"title":"Line Items","description":"Optional line items for credit detail"},"internal_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Internal Notes","description":"Internal notes (not visible to customer)"}},"type":"object","required":["customer_id","amount_cents"],"title":"CreditMemoCreate","description":"Request schema for creating a credit memo.","example":{"amount_cents":5000,"customer_id":"019ab37c-cust-7000-8000-000000000001","description":"Overcharged on invoice #INV-001","invoice_id":"019ab37c-inv1-7000-8000-000000000001","reason":"pricing_error"}},"CreditMemoLineItem":{"properties":{"description":{"type":"string","title":"Description","description":"Line item description"},"quantity":{"type":"integer","minimum":1.0,"title":"Quantity","description":"Quantity","default":1},"unit_price_cents":{"type":"integer","title":"Unit Price Cents","description":"Unit price in cents"},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Total amount in cents (qty * unit_price)"}},"type":"object","required":["description","unit_price_cents","amount_cents"],"title":"CreditMemoLineItem","description":"Line item for credit memo details."},"CreditMemoReasonEnum":{"type":"string","enum":["returned_goods","damaged_goods","service_issue","pricing_error","billing_adjustment","goodwill","duplicate_charge","other"],"title":"CreditMemoReasonEnum","description":"Standard reasons for issuing a credit memo."},"CreditMemoResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Credit memo ID"},"business_id":{"type":"string","title":"Business Id","description":"Business that issued the credit"},"customer_id":{"type":"string","title":"Customer Id","description":"Customer receiving the credit"},"invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Id","description":"Original invoice being credited"},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number","description":"Auto-generated credit memo number (e.g. CM-001)"},"status":{"type":"string","title":"Status","description":"Status: draft, issued, partially_applied, fully_applied, void"},"currency":{"type":"string","title":"Currency","description":"ISO currency code (e.g. USD)"},"amount":{"type":"integer","title":"Amount","description":"Total credit amount in cents"},"amount_in_dollars":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount In Dollars","description":"Total credit amount in dollars"},"amount_applied":{"type":"integer","title":"Amount Applied","description":"Amount applied in cents"},"amount_applied_in_dollars":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Applied In Dollars","description":"Amount applied in dollars"},"amount_remaining":{"type":"integer","title":"Amount Remaining","description":"Remaining amount in cents"},"amount_remaining_in_dollars":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Remaining In Dollars","description":"Remaining amount in dollars"},"issue_date":{"type":"string","format":"date","title":"Issue Date","description":"Date the credit memo was issued"},"applied_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Applied Date","description":"When credits were last applied"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Record creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"reason":{"type":"string","title":"Reason","description":"Reason code (e.g. pricing_error, refund, other)"},"reason_display":{"type":"string","title":"Reason Display","description":"Human-readable reason label"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the credit"},"internal_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Internal Notes","description":"Internal notes (not visible to customer)"},"line_items":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Line Items","description":"Detailed line items breakdown"},"voided_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Voided At","description":"When the credit memo was voided"},"voided_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voided Reason","description":"Reason for voiding"},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name","description":"Customer display name"},"invoice_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Number","description":"Original invoice number"},"applications":{"anyOf":[{"items":{"$ref":"#/components/schemas/CreditMemoApplicationResponse"},"type":"array"},{"type":"null"}],"title":"Applications","description":"Applications to invoices"},"can_be_applied":{"type":"boolean","title":"Can Be Applied","description":"Whether credits can be applied to invoices"},"can_be_voided":{"type":"boolean","title":"Can Be Voided","description":"Whether the credit memo can be voided"},"can_be_deleted":{"type":"boolean","title":"Can Be Deleted","description":"Whether the credit memo can be deleted (drafts only)"},"has_applications":{"type":"boolean","title":"Has Applications","description":"Whether any credits have been applied"}},"type":"object","required":["id","business_id","customer_id","status","currency","amount","amount_in_dollars","amount_applied","amount_applied_in_dollars","amount_remaining","amount_remaining_in_dollars","issue_date","created_at","updated_at","reason","reason_display","can_be_applied","can_be_voided","can_be_deleted","has_applications"],"title":"CreditMemoResponse","description":"Response schema for a credit memo.","example":{"amount":5000,"amount_applied":0,"amount_applied_in_dollars":0.0,"amount_in_dollars":50.0,"amount_remaining":5000,"amount_remaining_in_dollars":50.0,"business_id":"019ab37c-bus1-7000-8000-000000000001","can_be_applied":true,"can_be_deleted":false,"can_be_voided":true,"currency":"USD","customer_id":"019ab37c-cust-7000-8000-000000000001","description":"Overcharged on invoice #INV-001","has_applications":false,"id":"019ab37c-cm01-7000-8000-000000000001","issue_date":"2026-01-07","number":"CM-001","reason":"pricing_error","reason_display":"Pricing Error","status":"issued"}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}