{"openapi":"3.1.0","info":{"title":"InvoiceCow API","version":"1.0.0","summary":"Issuers, connections, payments and the invoices InvoiceCow issues for them.","description":"The API of one InvoiceCow organization. Send its token in every request:\n`Authorization: Bearer <token>`. An agent obtains a token through the device\nflow (`/api/v1/agent/device`, then `/api/v1/agent/token`); a person approves it\nonce. A person can also create a token in the dashboard, under API tokens.\n\nA token has one or more scopes: `read` reads; `write` adds and changes issuers,\nnumber patterns, products, mappings and the portal address, and imports CSV\nfiles; `connections` opens webhook and CSV connections and rotates their\nsecrets; `downloads` downloads documents. A download releases an invoice, as in\nthe dashboard.\n\nEvery write sends an `Idempotency-Key` header: a unique text of 1 to 255\ncharacters, the same when you retry. A write that succeeded runs once per key\nfor 24 hours. A retry of the same request answers the record as it is now,\nwith the header `Idempotent-Replayed: true`, and never a secret; the same key\nwith another request is refused. A refused or failed write changes nothing\nand leaves its key free.\n\nMoney is in minor units (cents) with its ISO 4217 currency. Times are ISO 8601\nin UTC. Lists come in pages of `limit` records (50 unless you ask, at most 100).\nA token may make 1000 requests per hour. An error is `{ code, message }`.\n","contact":{"url":"https://invoicecow.com/developers"}},"servers":[{"url":"https://invoicecow.com"}],"security":[{"token":[]}],"tags":[{"name":"Agent authorization"},{"name":"Organization"},{"name":"Issuers"},{"name":"Products"},{"name":"Connections"},{"name":"Payments"},{"name":"Documents"}],"paths":{"/api/v1/agent/device":{"post":{"tags":["Agent authorization"],"operationId":"requestDeviceCode","summary":"Ask for a device code and a user code (RFC 8628 §3.1).","description":"Give the person `verification_uri_complete`. The person signs in or signs up,\ncompares the user code with the one you show, and approves. Then poll\n`/api/v1/agent/token`.\n","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAuthorizationRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/DeviceAuthorizationRequest"}}}},"responses":{"200":{"description":"The codes and the link for the person.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAuthorization"}}}},"400":{"$ref":"#/components/responses/OAuthError"},"429":{"$ref":"#/components/responses/OAuthError"}}}},"/api/v1/agent/token":{"post":{"tags":["Agent authorization"],"operationId":"pollDeviceToken","summary":"Poll for the token (RFC 8628 §3.4).","description":"Poll no sooner than `interval` seconds after the last poll. `slow_down` adds 5\nseconds to the interval from then on. The answer that carries the token comes\nonce: keep the token in an environment variable or a secret store, never in\na file of a repository.\n","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTokenRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/DeviceTokenRequest"}}}},"responses":{"200":{"description":"The person approved. The token, once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceToken"}}}},"400":{"$ref":"#/components/responses/OAuthError"},"429":{"$ref":"#/components/responses/OAuthError"}}}},"/api/v1/organization":{"get":{"tags":["Organization"],"operationId":"getOrganization","summary":"Read the token's organization, the token's name and scopes, and the portal.","responses":{"200":{"description":"The organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/setup":{"get":{"tags":["Organization"],"operationId":"verifySetup","summary":"Check the setup an agent made, the last step of the recipe.","description":"Four checks: an issuer with its next invoice number, a live connection, the\nportal's address, and a numbered invoice. `ready` is true when all pass. Each\ncheck says what it found, or what is missing.\n","responses":{"200":{"description":"The checks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Setup"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/portal":{"get":{"tags":["Organization"],"operationId":"getPortal","summary":"Read the buyer portal's address and the texts that share it.","parameters":[{"$ref":"#/components/parameters/Language"}],"responses":{"200":{"description":"The portal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portal"}}}},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Organization"],"operationId":"setPortalSlug","summary":"Set the portal's address, invoicecow.com/<slug>.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/Language"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$","description":"3 to 40 lowercase letters, digits and dashes."}}}}}},"responses":{"200":{"description":"The portal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portal"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/issuers":{"get":{"tags":["Issuers"],"operationId":"listIssuers","summary":"List the issuer companies.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of issuers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuerPage"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Issuers"],"operationId":"createIssuer","summary":"Add an issuer company, the seller named on its invoices.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/IssuerInput"},{"required":["legal_name","country_code"]}]}}}},"responses":{"201":{"description":"The new issuer, with its two number series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/issuers/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Issuers"],"operationId":"getIssuer","summary":"Read an issuer.","responses":{"200":{"description":"The issuer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Issuers"],"operationId":"updateIssuer","summary":"Change an issuer. Issued documents keep the data they were issued with.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuerInput"}}}},"responses":{"200":{"description":"The issuer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Issuer"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/issuers/{issuer_id}/number_sequences":{"parameters":[{"$ref":"#/components/parameters/IssuerId"}],"get":{"tags":["Issuers"],"operationId":"listNumberSequences","summary":"List an issuer's number series.","responses":{"200":{"description":"The two series.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NumberSequence"}}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/issuers/{issuer_id}/number_sequences/{series}":{"parameters":[{"$ref":"#/components/parameters/IssuerId"},{"name":"series","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Series"}}],"patch":{"tags":["Issuers"],"operationId":"setNumberPattern","summary":"Set a series' number pattern. It applies to the next number; issued numbers never change.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberSequenceInput"}}}},"responses":{"200":{"description":"The series, with the number the next document takes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberSequence"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/products":{"get":{"tags":["Products"],"operationId":"listProducts","summary":"List the product catalog.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Products"],"operationId":"createProduct","summary":"Add a catalog product.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInput"}}}},"responses":{"201":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/products/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"patch":{"tags":["Products"],"operationId":"renameProduct","summary":"Rename a catalog product.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInput"}}}},"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connector_products":{"get":{"tags":["Products"],"operationId":"listConnectorProducts","summary":"List the products as each connection names them, with their catalog product.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of connector products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorProductPage"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connector_products/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"patch":{"tags":["Products"],"operationId":"mapConnectorProduct","summary":"Map a connector product to a catalog product, or remove the mapping with null.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id"],"properties":{"product_id":{"type":["string","null"],"format":"uuid"}}}}}},"responses":{"200":{"description":"The connector product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorProduct"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections":{"get":{"tags":["Connections"],"operationId":"listConnections","summary":"List the connections that bring sales in.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionPage"}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Connections"],"operationId":"createConnection","summary":"Open a signed webhook connection or a CSV connection (scope `connections`).","description":"A webhook connection's answer carries its `webhook_url` and its `secret`, once.\nKeep the secret where the application keeps its other secrets. A replay of this\nrequest never carries the secret; rotate it if it is lost. A person connects\nStripe in the dashboard.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["issuer_id","kind"],"properties":{"issuer_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["webhook","csv"]}}}}}},"responses":{"201":{"description":"The connection; a webhook connection with its secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections/stripe/authorizations":{"post":{"tags":["Connections"],"operationId":"startStripeAuthorization","summary":"Start connecting an issuer's Stripe account through the InvoiceCow Stripe App (scope `connections`).","description":"Returns the install link, valid for 30 minutes, once. The person opens it, installs\nthe app on Stripe, and comes back to InvoiceCow signed in as a person who manages\nthis organization. Read the result at the authorization. While the app is pending\nStripe review, the answer is 503 `stripe_app_pending_review`, and a person connects\nStripe in the dashboard with a restricted key.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["issuer_id"],"properties":{"issuer_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The authorization with its install link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAuthorization"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections/stripe/authorizations/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Connections"],"operationId":"getStripeAuthorization","summary":"Read an install of the Stripe App, its status and its connection.","responses":{"200":{"description":"The authorization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAuthorization"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Connections"],"operationId":"getConnection","summary":"Read a connection, for Stripe its status and the permissions its key needs.","responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections/{id}/rotate_secret":{"parameters":[{"$ref":"#/components/parameters/Id"}],"post":{"tags":["Connections"],"operationId":"rotateWebhookSecret","summary":"Make a new secret for a webhook connection; the old one stops at once (scope `connections`).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"The connection with its new secret, once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections/{connection_id}/imports":{"parameters":[{"$ref":"#/components/parameters/ConnectionId"}],"post":{"tags":["Connections"],"operationId":"importCsv","summary":"Upload a CSV file of sales to a CSV connection (at most 5 MB).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","contentMediaType":"text/csv"}}}}}},"responses":{"201":{"description":"The import. A large file runs in a job; read it again until its state is done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/connections/{connection_id}/imports/{id}":{"parameters":[{"$ref":"#/components/parameters/ConnectionId"},{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Connections"],"operationId":"getImport","summary":"Read an import and the outcome of each sale.","responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/payments":{"get":{"tags":["Payments"],"operationId":"listPayments","summary":"List the sales, newest first, with the dashboard's filters.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"issuer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"processor","in":"query","schema":{"type":"string"},"description":"For example stripe."},{"name":"buyer_country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"buyer_type","in":"query","schema":{"type":"string","enum":["business","consumer"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["awaiting_data","on_hold","late_review","issued","released","replaced","void","quarantined","refunded","fully_refunded","disputed","issued_late","late","imported","issued_by_stripe"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Paid on or after this day."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Paid on or before this day."},{"name":"min_amount","in":"query","schema":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},"description":"In the major unit."},{"name":"max_amount","in":"query","schema":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"},"description":"In the major unit."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Part of a number, a buyer's name, company, tax id or email, or the processor's id."}],"responses":{"200":{"description":"A page of payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPage"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/payments/not_yet_invoiced":{"get":{"tags":["Payments"],"operationId":"listNotYetInvoiced","summary":"The \"Not yet invoiced\" board: known deadlines first, the nearest first, then the unknown ones.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"issuer_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardPage"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/payments/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Payments"],"operationId":"getPayment","summary":"Read a sale, its lines, its invoice and the portal link.","responses":{"200":{"description":"The payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/invoices":{"get":{"tags":["Documents"],"operationId":"listInvoices","summary":"List the numbered invoices, newest first.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"issuer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"query","schema":{"$ref":"#/components/schemas/InvoiceKind"}},{"name":"state","in":"query","schema":{"type":"string","enum":["issued","released","replaced"]}},{"name":"delivery_state","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Issued on or after this day."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Issued on or before this day."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Part of the number."}],"responses":{"200":{"description":"A page of invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePage"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/invoices/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Documents"],"operationId":"getInvoice","summary":"Read an invoice, its states and its files.","responses":{"200":{"description":"The invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/invoices/{id}/pdf":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Documents"],"operationId":"downloadInvoice","summary":"Download the invoice's PDF (scope `downloads`). The download releases the invoice.","responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","contentMediaType":"application/pdf"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/credit_notes":{"get":{"tags":["Documents"],"operationId":"listCreditNotes","summary":"List the credit notes, newest first.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of credit notes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNotePage"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/credit_notes/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Documents"],"operationId":"getCreditNote","summary":"Read a credit note.","responses":{"200":{"description":"The credit note.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/credit_notes/{id}/pdf":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"tags":["Documents"],"operationId":"downloadCreditNote","summary":"Download the credit note's PDF (scope `downloads`).","responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","contentMediaType":"application/pdf"}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","description":"An API token of one organization."}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IssuerId":{"name":"issuer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ConnectionId":{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"Language":{"name":"language","in":"query","description":"The language of the texts that share the portal.","schema":{"$ref":"#/components/schemas/Language"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique text of 1 to 255 characters; the same when you retry.","schema":{"type":"string","minLength":1,"maxLength":255}}},"responses":{"Error":{"description":"An error. 400 a parameter is missing or wrong; 401 no valid token; 403 the token\nlacks the scope, was revoked, or its person no longer manages the organization;\n404 no such record in this organization; 409 a request with this\nIdempotency-Key still runs; 422 the values cannot be saved; 429 too many\nrequests.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OAuthError":{"description":"An error of the device flow (RFC 6749 §5.2, RFC 8628 §3.5).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}},"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"For the program","for example not_found or missing_scope.":null},"message":{"type":"string","description":"A sentence for the person."},"fields":{"type":"object","description":"For `invalid`, the messages per field.","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"OAuthError":{"type":"object","additionalProperties":false,"required":["error","error_description"],"properties":{"error":{"type":"string","enum":["authorization_pending","slow_down","access_denied","expired_token","invalid_grant","unsupported_grant_type","invalid_scope","invalid_request"]},"error_description":{"type":"string"}}},"Scope":{"type":"string","enum":["read","write","connections","downloads"]},"Language":{"type":"string","enum":["en","es","de","fr"]},"Series":{"type":"string","enum":["invoice","credit_note"]},"InvoiceKind":{"type":"string","enum":["invoice","simplified_invoice"]},"Pagination":{"type":"object","additionalProperties":false,"required":["page","limit","count","next_page"],"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"count":{"type":"integer","minimum":0},"next_page":{"type":["integer","null"]}}},"File":{"type":"object","additionalProperties":false,"required":["format","url"],"properties":{"format":{"type":"string","description":"pdf today; the structured formats join as InvoiceCow produces them."},"url":{"type":"string","format":"uri"}}},"DeviceAuthorizationRequest":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":"string","maxLength":60,"description":"The agent's name, for example Claude Code. Every poll sends it again."},"device_name":{"type":"string","maxLength":60,"description":"The machine's name."},"scope":{"type":"string","description":"The scopes, separated by spaces. Without it, read.","examples":["read write connections downloads"]}}},"DeviceAuthorization":{"type":"object","additionalProperties":false,"required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"],"properties":{"device_code":{"type":"string","description":"Secret; send it only to /api/v1/agent/token."},"user_code":{"type":"string","pattern":"^[B-DF-HJ-NP-TV-XZ]{4}-[B-DF-HJ-NP-TV-XZ]{4}$"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer","description":"Seconds."},"interval":{"type":"integer","description":"Seconds between polls."}}},"DeviceTokenRequest":{"type":"object","required":["grant_type","device_code","client_id"],"properties":{"grant_type":{"type":"string","const":"urn:ietf:params:oauth:grant-type:device_code"},"device_code":{"type":"string"},"client_id":{"type":"string","description":"The client_id of the device request. Another one gets invalid_grant."}}},"DeviceToken":{"type":"object","additionalProperties":false,"required":["access_token","token_type","scope","organization"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","const":"Bearer"},"scope":{"type":"string","description":"The scopes","separated by spaces.":null},"organization":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}},"Organization":{"type":"object","additionalProperties":false,"required":["id","name","token","portal"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"token":{"type":"object","additionalProperties":false,"required":["name","scopes"],"properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"}}}},"portal":{"$ref":"#/components/schemas/Portal"}}},"Setup":{"type":"object","additionalProperties":false,"required":["ready","checks"],"properties":{"ready":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","ok","message"],"properties":{"name":{"type":"string","enum":["issuer","connection","portal","invoice"]},"ok":{"type":"boolean"},"message":{"type":"string"}}}}}},"Portal":{"type":"object","additionalProperties":false,"required":["slug","url","state","receipt_line","stripe_receipt_text"],"properties":{"slug":{"type":["string","null"],"description":"Null until the portal has an address."},"url":{"type":["string","null"],"format":"uri","description":"The buyers' link."},"state":{"type":"string","enum":["open","closing","closed"]},"receipt_line":{"type":["string","null"],"description":"A line for the receipt email."},"stripe_receipt_text":{"type":["string","null"],"description":"For the custom message of Stripe's receipts."}}},"IssuerInput":{"type":"object","properties":{"legal_name":{"type":"string"},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"region":{"type":["string","null"]},"country_code":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2."},"tax_ids":{"type":"array","items":{"type":"string"},"description":"The company's tax ids, for example its EU VAT number. Replaces the list."},"default_language":{"$ref":"#/components/schemas/Language"},"brand_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"time_zone":{"type":"string","description":"An IANA time zone; the country's first zone when blank."},"hold_days":{"type":"integer","minimum":0,"maximum":90,"description":"Days to hold each invoice before issue."},"email_buyers":{"type":"boolean","description":"Email each document to its buyer."},"email_attaches_pdf":{"type":"boolean","description":"Attach the PDF to the email","besides the link.":null},"contact_email":{"type":["string","null"],"format":"email","description":"Where buyers' replies go; the owner's address when null."},"electronic_address":{"type":["string","null"],"description":"The seller's electronic address on e-invoices (BT-34), scheme:identifier with an EAS code, for example 0208:0123456749."},"contact_name":{"type":["string","null"],"maxLength":100},"contact_phone":{"type":["string","null"]}}},"Issuer":{"type":"object","additionalProperties":false,"required":["id","legal_name","address_line1","address_line2","city","postal_code","region","country_code","tax_ids","default_language","brand_color","time_zone","hold_days","email_buyers","email_attaches_pdf","contact_email","electronic_address","contact_name","contact_phone","number_sequences","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"legal_name":{"type":"string"},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"region":{"type":["string","null"]},"country_code":{"type":"string"},"tax_ids":{"type":"array","items":{"type":"string"}},"default_language":{"$ref":"#/components/schemas/Language"},"brand_color":{"type":["string","null"]},"time_zone":{"type":"string"},"hold_days":{"type":"integer"},"email_buyers":{"type":"boolean"},"email_attaches_pdf":{"type":"boolean"},"contact_email":{"type":["string","null"]},"electronic_address":{"type":["string","null"]},"contact_name":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"number_sequences":{"type":"array","items":{"$ref":"#/components/schemas/NumberSequence"}},"created_at":{"type":"string","format":"date-time"}}},"IssuerPage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Issuer"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"NumberSequenceInput":{"type":"object","properties":{"prefix":{"type":"string","description":"Text before the counter. {YYYY} becomes the issue year; it must be there when the count restarts every year.","examples":["{YYYY}-","INV-"]},"padding":{"type":"integer","minimum":1,"maximum":12,"description":"Digits of the counter."},"yearly_reset":{"type":"boolean","description":"The count restarts at 1 every year."}}},"NumberSequence":{"type":"object","additionalProperties":false,"required":["series","prefix","padding","yearly_reset","next_number"],"properties":{"series":{"$ref":"#/components/schemas/Series"},"prefix":{"type":"string"},"padding":{"type":"integer"},"yearly_reset":{"type":"boolean"},"next_number":{"type":"string","description":"The number the next document of the series takes today."}}},"ProductInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1}}},"Product":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ProductPage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"ConnectorProduct":{"type":"object","additionalProperties":false,"required":["id","connection_id","external_id","name","product_id"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"name":{"type":["string","null"]},"product_id":{"type":["string","null"],"format":"uuid"}}},"ConnectorProductPage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorProduct"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Connection":{"type":"object","additionalProperties":false,"required":["id","issuer_id","kind","live","processor_account_id","webhook_url","stripe_permissions","backfill","created_at","disconnected_at"],"properties":{"id":{"type":"string","format":"uuid"},"issuer_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["stripe","csv","webhook","shopify"]},"live":{"type":"boolean","description":"False after a disconnect."},"processor_account_id":{"type":["string","null"],"description":"The Stripe account, acct_..."},"webhook_url":{"type":["string","null"],"format":"uri","description":"Where the events of this connection go. Null for CSV and after a disconnect."},"stripe_permissions":{"type":["array","null"],"items":{"type":"string"},"description":"The read permissions a Stripe restricted key needs. Null unless Stripe."},"backfill":{"type":["object","null"],"additionalProperties":false,"required":["from","finished_at"],"properties":{"from":{"type":["string","null"],"format":"date"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"created_at":{"type":"string","format":"date-time"},"disconnected_at":{"type":["string","null"],"format":"date-time"},"secret":{"type":"string","description":"The webhook secret. Only the answer that made it carries it."}}},"StripeAuthorization":{"type":"object","additionalProperties":false,"required":["id","issuer_id","status","reason","message","url","connection_id","expires_at","permissions"],"properties":{"id":{"type":"string","format":"uuid"},"issuer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","connected","refused","expired"]},"reason":{"type":["string","null"],"description":"Why it was refused, for example access_denied."},"message":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri","description":"The install link, only in the answer that started it."},"connection_id":{"type":["string","null"],"format":"uuid"},"expires_at":{"type":"string","format":"date-time"},"permissions":{"type":"array","items":{"type":"string"},"description":"The read permissions the app asks for."}}},"ConnectionPage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Import":{"type":"object","additionalProperties":false,"required":["id","connection_id","filename","state","rows_count","counts","error","rows"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"state":{"type":"string","enum":["queued","processing","done","failed"]},"rows_count":{"type":"integer"},"counts":{"type":"object","description":"Sales per outcome.","additionalProperties":{"type":"integer"}},"error":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["rows","outcome","reason","message","payment_id"],"properties":{"rows":{"type":"array","items":{"type":"integer"},"description":"The file's row numbers of one sale."},"outcome":{"type":"string","enum":["recorded","quarantined","rejected"]},"reason":{"type":["string","null"]},"message":{"type":["string","null"]},"payment_id":{"type":["string","null"],"format":"uuid"}}}}}},"Buyer":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":["string","null"]},"name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"region":{"type":["string","null"]},"country_code":{"type":["string","null"]},"tax_id":{"type":["string","null"]},"po_number":{"type":["string","null"]},"language":{"type":["string","null"]},"declared_type":{"type":["string","null"]}}},"Line":{"type":"object","additionalProperties":false,"required":["description","quantity","unit_amount_cents","net_cents","tax_cents","gross_cents","taxes"],"properties":{"description":{"type":"string"},"quantity":{"type":"string","description":"A decimal."},"unit_amount_cents":{"type":["integer","null"]},"net_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"gross_cents":{"type":"integer"},"taxes":{"type":"array","items":{"type":"object"}}}},"PaymentSummary":{"type":"object","additionalProperties":false,"description":"A sale in a list of many. GET /api/v1/payments/{id} has the rest.","required":["id","issuer_id","processor","processor_payment_id","merchant_payment_id","currency","amount_cents","paid_at","deadline_on","status","buyer","portal_url"],"properties":{"id":{"type":"string","format":"uuid"},"issuer_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_payment_id":{"type":"string"},"merchant_payment_id":{"type":["string","null"]},"currency":{"type":"string"},"amount_cents":{"type":"integer"},"paid_at":{"type":"string","format":"date-time"},"deadline_on":{"type":["string","null"],"format":"date"},"status":{"type":"array","items":{"type":"string"}},"buyer":{"$ref":"#/components/schemas/Buyer"},"portal_url":{"type":["string","null"],"format":"uri"}}},"Payment":{"type":"object","additionalProperties":false,"required":["id","issuer_id","connection_id","processor","processor_payment_id","merchant_payment_id","source","currency","amount_cents","refunded_cents","paid_at","deadline_on","issued_by","status","quarantine","buyer","lines","invoice","portal_url"],"properties":{"id":{"type":"string","format":"uuid"},"issuer_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_payment_id":{"type":"string"},"merchant_payment_id":{"type":["string","null"]},"source":{"type":"string","enum":["import","backfill","live"]},"currency":{"type":"string"},"amount_cents":{"type":"integer"},"refunded_cents":{"type":"integer"},"paid_at":{"type":"string","format":"date-time"},"deadline_on":{"type":["string","null"],"format":"date","description":"The legal deadline to issue; null when unknown."},"issued_by":{"type":"string","enum":["self","self_via_stripe","platform","none"],"description":"Who issues this sale's document. platform is a seller of record; InvoiceCow never invoices it."},"status":{"type":"array","items":{"type":"string"},"description":"The status tags, as the dashboard shows them."},"quarantine":{"type":["object","null"],"additionalProperties":false,"required":["reason","message"],"properties":{"reason":{"type":"string"},"message":{"type":"string"}}},"buyer":{"$ref":"#/components/schemas/Buyer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/Line"}},"invoice":{"type":["object","null"],"additionalProperties":false,"required":["id","number","state","missing_fields"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":["string","null"],"description":"Null until issued."},"state":{"type":"string","enum":["awaiting_data","on_hold","late_review","void","issued","released","replaced"]},"missing_fields":{"type":"array","items":{"type":"string"}}}},"portal_url":{"type":["string","null"],"format":"uri","description":"Where the buyer adds details and downloads."}}},"PaymentPage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"BoardRow":{"type":"object","additionalProperties":false,"required":["payment","days_left","blocking_reason","message","issuable"],"properties":{"payment":{"$ref":"#/components/schemas/PaymentSummary"},"days_left":{"type":["integer","null"],"description":"Null when the deadline is unknown."},"blocking_reason":{"type":"string","enum":["quarantined","awaiting_data","on_hold","late_review"]},"message":{"type":"string"},"issuable":{"type":"boolean","description":"A person can issue it now from the dashboard."}}},"BoardPage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardRow"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Invoice":{"type":"object","additionalProperties":false,"required":["id","number","kind","state","delivery_state","issuer_id","payment_id","replaces_invoice_id","issued_on","issued_at","issued_late","released_at","currency","total_cents","rule_version","files"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":["string","null"]},"kind":{"oneOf":[{"$ref":"#/components/schemas/InvoiceKind"},{"type":"null"}]},"state":{"type":"string","enum":["awaiting_data","on_hold","late_review","void","issued","released","replaced"]},"delivery_state":{"type":"string"},"issuer_id":{"type":"string","format":"uuid"},"payment_id":{"type":"string","format":"uuid"},"replaces_invoice_id":{"type":["string","null"],"format":"uuid"},"issued_on":{"type":["string","null"],"format":"date"},"issued_at":{"type":["string","null"],"format":"date-time"},"issued_late":{"type":"boolean"},"released_at":{"type":["string","null"],"format":"date-time"},"currency":{"type":["string","null"]},"total_cents":{"type":["integer","null"]},"rule_version":{"type":["string","null"]},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}},"InvoicePage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"CreditNote":{"type":"object","additionalProperties":false,"required":["id","number","kind","delivery_state","issuer_id","payment_id","invoice_id","issued_on","issued_at","currency","amount_cents","files"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"string"},"kind":{"type":"string","enum":["refund","correction"]},"delivery_state":{"type":"string"},"issuer_id":{"type":"string","format":"uuid"},"payment_id":{"type":"string","format":"uuid"},"invoice_id":{"type":"string","format":"uuid"},"issued_on":{"type":"string","format":"date"},"issued_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"amount_cents":{"type":"integer"},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}},"CreditNotePage":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CreditNote"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}