{"openapi":"3.1.0","info":{"title":"Tabba Public API","version":"1.0.0","description":"REST API for driving invoicing and revenue recognition in Tabba from your own tooling. Authenticate with a `Bearer tpk_…` API key minted in Settings → Developers. Additive-only within `/api/v1`."},"servers":[{"url":"https://www.tabba.io/api/v1","description":"Production"}],"tags":[{"name":"accruals"},{"name":"config"},{"name":"credit-notes"},{"name":"customers"},{"name":"invoices"},{"name":"products"},{"name":"recognition"},{"name":"recurring-series"},{"name":"users"},{"name":"work-registrations"}],"paths":{"/accruals":{"get":{"operationId":"getAccruals","summary":"Read a customer's accrual state for one month (draft/booked + Dinero GUID)","tags":["accruals"],"parameters":[{"name":"customer","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"month","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"accrual"},"id":{"type":"string"},"customer_id":{"type":"string"},"accrual_month":{"type":"string"},"original_accrual_month":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["draft","booked"]},"dinero_voucher_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_voucher_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"booked_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","customer_id","accrual_month","original_accrual_month","status","dinero_voucher_guid","dinero_voucher_number","booked_at"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/credit-notes":{"post":{"operationId":"postCreditNotes","summary":"Raise a credit note (full/partial; external_id required — idempotent; 200+send_error on booked-but-send-failed)","tags":["credit-notes"],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"credit_note"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoice_id":{"type":"string"},"customer_id":{"type":"string"},"kind":{"type":"string","enum":["full","partial"]},"status":{"type":"string","enum":["draft","issued"]},"dinero_credit_note_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_credit_note_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"send_error":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"invoice_line_id":{"type":"string"},"amount":{"type":"number"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","invoice_line_id","amount","position"],"additionalProperties":false}}},"required":["object","id","external_id","invoice_id","customer_id","kind","status","dinero_credit_note_guid","dinero_credit_note_number","issued_at","send_error","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":128},"invoice":{"type":"string","minLength":1},"kind":{"type":"string","enum":["full","partial"]},"credit_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"lines":{"type":"array","items":{"type":"object","properties":{"invoice_line_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"amount":{"type":"number","minimum":0}},"required":["invoice_line_id","amount"]}}},"required":["external_id","invoice","kind","credit_date"]}}}}}},"/customers":{"get":{"operationId":"getCustomers","summary":"List active customers (cursor-paginated; filters: external_id, updated_since)","tags":["customers"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"customer"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string"},"country_key":{"type":"string"},"is_person":{"type":"boolean"},"send_method":{"type":"string","enum":["email","einvoice"]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"webpage":{"anyOf":[{"type":"string"},{"type":"null"}]},"att_person":{"anyOf":[{"type":"string"},{"type":"null"}]},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"se_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"p_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"ean_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"use_cvr":{"type":"boolean"},"company_type_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_language_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_currency_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_number_of_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"invoice_mail_out_option_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_mean":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","external_id","name","country_key","is_person","send_method","street","zip_code","city","phone","email","webpage","att_person","vat_number","se_number","p_number","ean_number","use_cvr","company_type_key","preferred_invoice_language_key","preferred_invoice_currency_key","external_reference","payment_condition_type","payment_condition_number_of_days","invoice_mail_out_option_key","payment_mean"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"post":{"operationId":"postCustomers","summary":"Create a customer or upsert by external_id (syncs to Dinero)","tags":["customers"],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"customer"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string"},"country_key":{"type":"string"},"is_person":{"type":"boolean"},"send_method":{"type":"string","enum":["email","einvoice"]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"webpage":{"anyOf":[{"type":"string"},{"type":"null"}]},"att_person":{"anyOf":[{"type":"string"},{"type":"null"}]},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"se_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"p_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"ean_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"use_cvr":{"type":"boolean"},"company_type_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_language_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_currency_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_number_of_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"invoice_mail_out_option_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_mean":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","external_id","name","country_key","is_person","send_method","street","zip_code","city","phone","email","webpage","att_person","vat_number","se_number","p_number","ean_number","use_cvr","company_type_key","preferred_invoice_language_key","preferred_invoice_currency_key","external_reference","payment_condition_type","payment_condition_number_of_days","invoice_mail_out_option_key","payment_mean"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"country_key":{"type":"string","minLength":2},"is_person":{"type":"boolean"},"send_method":{"type":"string","enum":["email","einvoice"]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"webpage":{"anyOf":[{"type":"string"},{"type":"null"}]},"att_person":{"anyOf":[{"type":"string"},{"type":"null"}]},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"se_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"p_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"ean_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"use_cvr":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"company_type_key":{"anyOf":[{"type":"string","enum":["EmptyCompanyType","SoleProprietorship","PrivateLimitedCompany","PublicLimitedCompany","GeneralPartnership","LimitedPartnership","LimitedLiabilityCooperative","LimitedLiabilityVoluntaryAssociation","LimitedLiabilityCompany","EntreprenurLimitedCompany","Union","VoluntaryUnion","SmallPersonallyOwnedCompany","TrustFund","Others"]},{"type":"null"}]},"preferred_invoice_language_key":{"anyOf":[{"type":"string","enum":["da","en","de","sv","no"]},{"type":"null"}]},"preferred_invoice_currency_key":{"anyOf":[{"type":"string","enum":["DKK","EUR","USD","SEK","NOK","GBP"]},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_type":{"anyOf":[{"type":"string","enum":["Netto","NettoCash","CurrentMonthOut"]},{"type":"null"}]},"payment_condition_number_of_days":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"invoice_mail_out_option_key":{"anyOf":[{"type":"string","enum":["VAT","GLN","SE","P"]},{"type":"null"}]},"payment_mean":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","country_key","is_person","send_method"]}}}}}},"/customers/{ref}":{"get":{"operationId":"getCustomersRef","summary":"Fetch a customer by ext:/UUID reference","tags":["customers"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"customer"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string"},"country_key":{"type":"string"},"is_person":{"type":"boolean"},"send_method":{"type":"string","enum":["email","einvoice"]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"webpage":{"anyOf":[{"type":"string"},{"type":"null"}]},"att_person":{"anyOf":[{"type":"string"},{"type":"null"}]},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"se_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"p_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"ean_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"use_cvr":{"type":"boolean"},"company_type_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_language_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_currency_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_number_of_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"invoice_mail_out_option_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_mean":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","external_id","name","country_key","is_person","send_method","street","zip_code","city","phone","email","webpage","att_person","vat_number","se_number","p_number","ean_number","use_cvr","company_type_key","preferred_invoice_language_key","preferred_invoice_currency_key","external_reference","payment_condition_type","payment_condition_number_of_days","invoice_mail_out_option_key","payment_mean"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"patch":{"operationId":"patchCustomersRef","summary":"Partial update of a customer (routes non-external_id changes through the Dinero-sync service)","tags":["customers"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"customer"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string"},"country_key":{"type":"string"},"is_person":{"type":"boolean"},"send_method":{"type":"string","enum":["email","einvoice"]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"webpage":{"anyOf":[{"type":"string"},{"type":"null"}]},"att_person":{"anyOf":[{"type":"string"},{"type":"null"}]},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"se_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"p_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"ean_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"use_cvr":{"type":"boolean"},"company_type_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_language_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_invoice_currency_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_number_of_days":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"invoice_mail_out_option_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_mean":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","external_id","name","country_key","is_person","send_method","street","zip_code","city","phone","email","webpage","att_person","vat_number","se_number","p_number","ean_number","use_cvr","company_type_key","preferred_invoice_language_key","preferred_invoice_currency_key","external_reference","payment_condition_type","payment_condition_number_of_days","invoice_mail_out_option_key","payment_mean"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"name":{"type":"string","minLength":1},"country_key":{"type":"string","minLength":2},"is_person":{"type":"boolean"},"send_method":{"type":"string","enum":["email","einvoice"]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"webpage":{"anyOf":[{"type":"string"},{"type":"null"}]},"att_person":{"anyOf":[{"type":"string"},{"type":"null"}]},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"se_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"p_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"ean_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"use_cvr":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"company_type_key":{"anyOf":[{"type":"string","enum":["EmptyCompanyType","SoleProprietorship","PrivateLimitedCompany","PublicLimitedCompany","GeneralPartnership","LimitedPartnership","LimitedLiabilityCooperative","LimitedLiabilityVoluntaryAssociation","LimitedLiabilityCompany","EntreprenurLimitedCompany","Union","VoluntaryUnion","SmallPersonallyOwnedCompany","TrustFund","Others"]},{"type":"null"}]},"preferred_invoice_language_key":{"anyOf":[{"type":"string","enum":["da","en","de","sv","no"]},{"type":"null"}]},"preferred_invoice_currency_key":{"anyOf":[{"type":"string","enum":["DKK","EUR","USD","SEK","NOK","GBP"]},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_condition_type":{"anyOf":[{"type":"string","enum":["Netto","NettoCash","CurrentMonthOut"]},{"type":"null"}]},"payment_condition_number_of_days":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"invoice_mail_out_option_key":{"anyOf":[{"type":"string","enum":["VAT","GLN","SE","P"]},{"type":"null"}]},"payment_mean":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}}},"delete":{"operationId":"deleteCustomersRef","summary":"Delete a customer (blocked-by-bookings → 409 DELETE_BLOCKED_BY_BOOKINGS)","tags":["customers"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"customer"},"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["object","id","deleted"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/invoices/{ref}/credit-notes":{"get":{"operationId":"getInvoicesRefCreditNotes","summary":"List an invoice's credit notes (cursor-paginated; filter: updated_since)","tags":["invoices"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"credit_note"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"invoice_id":{"type":"string"},"customer_id":{"type":"string"},"kind":{"type":"string","enum":["full","partial"]},"status":{"type":"string","enum":["draft","issued"]},"dinero_credit_note_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_credit_note_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"send_error":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"invoice_line_id":{"type":"string"},"amount":{"type":"number"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","invoice_line_id","amount","position"],"additionalProperties":false}}},"required":["object","id","external_id","invoice_id","customer_id","kind","status","dinero_credit_note_guid","dinero_credit_note_number","issued_at","send_error","lines"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/invoices/{ref}/issue":{"post":{"operationId":"postInvoicesRefIssue","summary":"Issue a one-time invoice on demand (synchronous, idempotent; 200+send_error on booked-but-send-failed)","tags":["invoices"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"auto_send":{"type":"boolean"},"status":{"type":"string","enum":["draft","issued"]},"dinero_invoice_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_invoice_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["id","product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}},"send_error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","external_id","customer_id","currency","issue_date","title","auto_send","status","dinero_invoice_guid","dinero_invoice_number","issued_at","lines","send_error"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/invoices/{ref}/recognition":{"get":{"operationId":"getInvoicesRefRecognition","summary":"Read per-line + per-invoice recognition (earned/billed/deferred/WIP)","tags":["invoices"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"invoice_recognition"},"invoice_id":{"type":"string"},"customer_id":{"type":"string"},"currency":{"type":"string"},"earned":{"type":"number"},"billed":{"type":"number"},"deferred":{"type":"number"},"wip":{"type":"number"},"invoice_value":{"type":"number"},"lines":{"type":"array","items":{"type":"object","properties":{"invoice_line_id":{"type":"string"},"description":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"earned":{"type":"number"},"billed":{"type":"number"},"deferred":{"type":"number"},"wip":{"type":"number"},"invoice_value":{"type":"number"}},"required":["invoice_line_id","description","recognition_method","earned","billed","deferred","wip","invoice_value"],"additionalProperties":false}}},"required":["object","invoice_id","customer_id","currency","earned","billed","deferred","wip","invoice_value","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/invoices":{"get":{"operationId":"getInvoices","summary":"List one-time invoices (cursor-paginated; filters: customer, status, external_id, updated_since)","tags":["invoices"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"customer","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","issued"]}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"auto_send":{"type":"boolean"},"status":{"type":"string","enum":["draft","issued"]},"dinero_invoice_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_invoice_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["id","product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","issue_date","title","auto_send","status","dinero_invoice_guid","dinero_invoice_number","issued_at","lines"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"post":{"operationId":"postInvoices","summary":"Create a one-time invoice (external_id required — upserts on repeat)","tags":["invoices"],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"auto_send":{"type":"boolean"},"status":{"type":"string","enum":["draft","issued"]},"dinero_invoice_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_invoice_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["id","product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","issue_date","title","auto_send","status","dinero_invoice_guid","dinero_invoice_number","issued_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"currency":{"type":"string","minLength":3},"auto_send":{"type":"boolean"},"lines":{"minItems":1,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":0,"maximum":9007199254740991},"assignees":{"minItems":1,"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"]}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"]}},"external_id":{"type":"string","minLength":1,"maxLength":128},"issue_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]}},"required":["customer_id","currency","lines","external_id"]}}}}}},"/products":{"get":{"operationId":"getProducts","summary":"List products for the integration (revenue account, unit, default price, external_id)","tags":["products"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"product"},"id":{"type":"string"},"product_number":{"type":"string"},"name":{"type":"string"},"account_number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit":{"type":"string"},"default_price":{"type":"number"},"quantity":{"type":"number"},"comments":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","product_number","name","account_number","unit","default_price","quantity","comments","external_id","external_reference"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"post":{"operationId":"postProducts","summary":"Create a product (Dinero-synced). If external_id is present, upserts on it.","tags":["products"],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"product"},"id":{"type":"string"},"product_number":{"type":"string"},"name":{"type":"string"},"account_number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit":{"type":"string"},"default_price":{"type":"number"},"quantity":{"type":"number"},"comments":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","product_number","name","account_number","unit","default_price","quantity","comments","external_id","external_reference"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_number":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"account_number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"unit":{"type":"string","minLength":1},"default_price":{"type":"number","minimum":0},"quantity":{"default":1,"type":"number","exclusiveMinimum":0},"comments":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}]},"external_id":{"type":"string","minLength":1,"maxLength":128}},"required":["product_number","name","account_number","unit","default_price"]}}}}}},"/products/{ref}":{"get":{"operationId":"getProductsRef","summary":"Fetch a single product by ext:/UUID reference","tags":["products"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"product"},"id":{"type":"string"},"product_number":{"type":"string"},"name":{"type":"string"},"account_number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit":{"type":"string"},"default_price":{"type":"number"},"quantity":{"type":"number"},"comments":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","product_number","name","account_number","unit","default_price","quantity","comments","external_id","external_reference"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"patch":{"operationId":"patchProductsRef","summary":"Update a product (Dinero-synced). external_id can be stamped or cleared.","tags":["products"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"product"},"id":{"type":"string"},"product_number":{"type":"string"},"name":{"type":"string"},"account_number":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unit":{"type":"string"},"default_price":{"type":"number"},"quantity":{"type":"number"},"comments":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","product_number","name","account_number","unit","default_price","quantity","comments","external_id","external_reference"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_number":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"account_number":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"unit":{"type":"string","minLength":1},"default_price":{"type":"number","minimum":0},"quantity":{"default":1,"type":"number","exclusiveMinimum":0},"comments":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]}},"required":["product_number","name","account_number","unit","default_price"]}}}}},"delete":{"operationId":"deleteProductsRef","summary":"Delete a product (Dinero-first). 204 No Content on success.","tags":["products"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/recurring-series/{ref}/cancel":{"post":{"operationId":"postRecurringSeriesRefCancel","summary":"Cancel a recurring series (idempotent) — no new occurrences generated; already-issued invoices run to completion","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"recurring_series"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"],"additionalProperties":false}]},"status":{"type":"string","enum":["draft","active","cancelled"]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","frequency","start_date","end_date","issue_timing","status","cancelled_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/recurring-series/{ref}/lines":{"post":{"operationId":"postRecurringSeriesRefLines","summary":"Add a series line (this_and_following) or one-time line (this_only) to an existing recurring series","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"series_line_edit"},"line_id":{"type":"string"},"line_kind":{"type":"string","enum":["series","one_time"]},"scope":{"type":"string","enum":["this_only","this_and_following"]},"period":{"type":"string"}},"required":["object","line_id","line_kind","scope","period"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["this_only","this_and_following"]},"period":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"line":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":0,"maximum":9007199254740991},"assignees":{"minItems":1,"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"]}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"]}},"required":["scope","line"]}}}}}},"/recurring-series/{ref}/occurrences/{period}":{"get":{"operationId":"getRecurringSeriesRefOccurrencesPeriod","summary":"Read a single occurrence by period (YYYY-MM-DD, matching the occurrence anchor)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"occurrence"},"series_id":{"type":"string"},"period":{"type":"string"},"period_from":{"type":"string"},"period_to":{"type":"string"},"issue_date":{"type":"string"},"is_final_partial":{"type":"boolean"},"status":{"type":"string","enum":["scheduled","issued","skipped"]},"invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","series_id","period","period_from","period_to","issue_date","is_final_partial","status","invoice_id"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/recurring-series/{ref}":{"get":{"operationId":"getRecurringSeriesRef","summary":"Fetch a recurring series by ext:/UUID reference (fat: base lines + roster)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"recurring_series"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"],"additionalProperties":false}]},"status":{"type":"string","enum":["draft","active","cancelled"]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","frequency","start_date","end_date","issue_timing","status","cancelled_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"patch":{"operationId":"patchRecurringSeriesRef","summary":"Update a recurring series header (cadence + horizon + issue-timing + customer + currency + optional external_id)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"recurring_series"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"],"additionalProperties":false}]},"status":{"type":"string","enum":["draft","active","cancelled"]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","frequency","start_date","end_date","issue_timing","status","cancelled_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"currency":{"type":"string","minLength":3},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"]}]},"external_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]}},"required":["customer_id","currency","frequency","start_date","end_date","issue_timing"]}}}}}},"/users/{ref}":{"patch":{"operationId":"patchUsersRef","summary":"Tag an existing user with an external_id (external_id is the only patchable field)","tags":["users"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"user"},"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"role":{"type":"string","enum":["admin","standard"]},"default_hourly_rate":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","name","email","role","default_hourly_rate","external_id"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["external_id"]}}}}},"get":{"operationId":"getUsersRef","summary":"Fetch a single user by ext:/email:/UUID reference","tags":["users"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"user"},"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"role":{"type":"string","enum":["admin","standard"]},"default_hourly_rate":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","name","email","role","default_hourly_rate","external_id"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/work-registrations":{"put":{"operationId":"putWorkRegistrations","summary":"Register work (absolute-set on hours + completion, occurrence-explicit) on a line + user; single-item; both metrics optional","tags":["work-registrations"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"work_registration"},"invoice_line_id":{"type":"string"},"user_id":{"type":"string"},"accrual_month":{"type":"string"},"hours_delta":{"anyOf":[{"type":"number"},{"type":"null"}]},"completion_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","invoice_line_id","user_id","accrual_month","hours_delta","completion_rate","external_id"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"string","minLength":1},"occurrence":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"invoice":{"type":"string","minLength":1},"line":{"type":"string","minLength":1},"user":{"type":"string","minLength":1},"hours":{"anyOf":[{"type":"number","minimum":0,"maximum":1000000},{"type":"null"}]},"completion_rate":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]}},"required":["line","user"]}}}}}},"/config":{"get":{"operationId":"getConfig","summary":"Read invoicing configuration (base currency + WIP / deferred accounts)","tags":["config"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"config"},"integration_id":{"type":"string"},"base_currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"wip_account_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"deferred_revenue_account_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["object","integration_id","base_currency","wip_account_number","deferred_revenue_account_number"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/users":{"get":{"operationId":"getUsers","summary":"List account users (id, name, email, role, default hourly rate, external_id)","tags":["users"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"user"},"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"role":{"type":"string","enum":["admin","standard"]},"default_hourly_rate":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","name","email","role","default_hourly_rate","external_id"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/invoices/{ref}":{"get":{"operationId":"getInvoicesRef","summary":"Fetch a one-time invoice by ext:/UUID reference (fat: lines + assignees)","tags":["invoices"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"auto_send":{"type":"boolean"},"status":{"type":"string","enum":["draft","issued"]},"dinero_invoice_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_invoice_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["id","product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","issue_date","title","auto_send","status","dinero_invoice_guid","dinero_invoice_number","issued_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"patch":{"operationId":"patchInvoicesRef","summary":"Update a draft invoice (freeze-guarded — 409 on issued)","tags":["invoices"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"auto_send":{"type":"boolean"},"status":{"type":"string","enum":["draft","issued"]},"dinero_invoice_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_invoice_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["id","product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","issue_date","title","auto_send","status","dinero_invoice_guid","dinero_invoice_number","issued_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"currency":{"type":"string","minLength":3},"auto_send":{"type":"boolean"},"lines":{"minItems":1,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":0,"maximum":9007199254740991},"assignees":{"minItems":1,"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"]}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"]}},"external_id":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}]},"issue_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}]}},"required":["customer_id","currency","lines","issue_date","title"]}}}}},"delete":{"operationId":"deleteInvoicesRef","summary":"Delete a draft invoice (freeze-guarded — 409 on issued)","tags":["invoices"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/recurring-series":{"get":{"operationId":"getRecurringSeries","summary":"List recurring series (cursor-paginated; filters: customer, status, external_id, updated_since)","tags":["recurring-series"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"customer","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","active","cancelled"]}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"recurring_series"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"],"additionalProperties":false}]},"status":{"type":"string","enum":["draft","active","cancelled"]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","frequency","start_date","end_date","issue_timing","status","cancelled_at","lines"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"},"post":{"operationId":"postRecurringSeries","summary":"Create a recurring series with base lines (external_id required — upserts on repeat)","tags":["recurring-series"],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"recurring_series"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"],"additionalProperties":false}]},"status":{"type":"string","enum":["draft","active","cancelled"]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}}},"required":["object","id","external_id","customer_id","currency","frequency","start_date","end_date","issue_timing","status","cancelled_at","lines"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"currency":{"type":"string","minLength":3},"frequency":{"type":"string","enum":["monthly","quarterly","semi-annual","annual"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"issue_timing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"start-of-period"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"end-of-period"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"day":{"type":"integer","minimum":1,"maximum":31},"month_offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["mode","day","month_offset"]}]},"external_id":{"type":"string","minLength":1,"maxLength":128},"lines":{"minItems":1,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":0,"maximum":9007199254740991},"assignees":{"minItems":1,"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"]}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"]}}},"required":["customer_id","currency","frequency","start_date","end_date","issue_timing","external_id","lines"]}}}}}},"/recurring-series/{ref}/lines/{lineRef}":{"patch":{"operationId":"patchRecurringSeriesRefLinesLineRef","summary":"Edit a series line (this_only / this_and_following) or a one-time line (scope ignored)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"lineRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"series_line_edit"},"line_id":{"type":"string"},"line_kind":{"type":"string","enum":["series","one_time"]},"scope":{"type":"string","enum":["this_only","this_and_following"]},"period":{"type":"string"}},"required":["object","line_id","line_kind","scope","period"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["this_only","this_and_following"]},"period":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"line":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":0,"maximum":9007199254740991},"assignees":{"minItems":1,"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"]}}},"required":["product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"]}},"required":["scope","period","line"]}}}}},"delete":{"operationId":"deleteRecurringSeriesRefLinesLineRef","summary":"Delete a series line (this_only / this_and_following) or a one-time line (whole line, scope ignored)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"lineRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["this_only","this_and_following"]}},{"name":"period","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"204":{"description":"Success"},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/recurring-series/{ref}/occurrences":{"get":{"operationId":"getRecurringSeriesRefOccurrences","summary":"List a series occurrences (past + upcoming, with billing periods + status)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"occurrence"},"series_id":{"type":"string"},"period":{"type":"string"},"period_from":{"type":"string"},"period_to":{"type":"string"},"issue_date":{"type":"string"},"is_final_partial":{"type":"boolean"},"status":{"type":"string","enum":["scheduled","issued","skipped"]},"invoice_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","series_id","period","period_from","period_to","issue_date","is_final_partial","status","invoice_id"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}},"/recurring-series/{ref}/occurrences/{period}/issue":{"post":{"operationId":"postRecurringSeriesRefOccurrencesPeriodIssue","summary":"Materialise (if needed) then issue a recurring-series occurrence (synchronous, idempotent; 200+send_error on booked-but-send-failed)","tags":["recurring-series"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"invoice"},"id":{"type":"string"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"customer_id":{"type":"string"},"currency":{"type":"string"},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"auto_send":{"type":"boolean"},"status":{"type":"string","enum":["draft","issued"]},"dinero_invoice_guid":{"anyOf":[{"type":"string"},{"type":"null"}]},"dinero_invoice_number":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"recognition_method":{"type":"string","enum":["value","hourly"]},"agreed_value":{"anyOf":[{"type":"number"},{"type":"null"}]},"hourly_rate":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount":{"anyOf":[{"type":"number"},{"type":"null"}]},"description_override":{"anyOf":[{"type":"string"},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"assignees":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"distribution_percentage":{"type":"number"},"hourly_rate_override":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["user_id","distribution_percentage","hourly_rate_override"],"additionalProperties":false}}},"required":["id","product_id","recognition_method","agreed_value","hourly_rate","discount","description_override","position","assignees"],"additionalProperties":false}},"send_error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","id","external_id","customer_id","currency","issue_date","title","auto_send","status","dinero_invoice_guid","dinero_invoice_number","issued_at","lines","send_error"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read_write"}},"/recognition":{"get":{"operationId":"getRecognition","summary":"Per-customer recognition roll-up (recognized vs invoiced, base currency)","tags":["recognition"],"parameters":[{"name":"customer","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"customer_recognition"},"customer_id":{"type":"string"},"currency":{"type":"string"},"recognized":{"type":"number"},"invoiced":{"type":"number"},"earned":{"type":"number"},"billed":{"type":"number"},"deferred":{"type":"number"},"wip":{"type":"number"}},"required":["object","customer_id","currency","recognized","invoiced","earned","billed","deferred","wip"],"additionalProperties":false}}}},"400":{"description":"Malformed request body or path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Insufficient scope (e.g. `read` key on a write endpoint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found (or invisible to this integration).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Typed business-rule conflict (e.g. INVOICE_ALREADY_ISSUED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Validation failed — see `field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate-limited — check `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"x-scope":"read"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (tpk_…)"}},"schemas":{"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"field_errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"request_id":{"type":"string"}},"required":["type","code","message","request_id"]}},"required":["error"]}}},"security":[{"bearerAuth":[]}]}