{"openapi":"3.1.0","info":{"title":"PayoutEngine API","version":"1.0.0","description":"A read-only HTTP API over the commission data PayoutEngine calculates: reps, periods, payouts with their line items, statements with the full calculation trace, and the payroll records of money that has left. Every response is JSON. Every money value is a decimal string, never a JSON number."},"servers":[{"url":"/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/reps":{"get":{"operationId":"reps","summary":"List reps","description":"Every sales rep at this organization, including those who have left, so the rep named on an older payout still resolves. Ordered oldest first and paged by cursor.","parameters":[{"name":"starting_after","in":"query","required":false,"schema":{"type":"string"},"description":"Continue the list after this id. Use the next_cursor value from your previous response, or omit it for the first page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"How many records to return. Defaults to 50, and values above 200 are served 200."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/reps/{id}":{"get":{"operationId":"rep","summary":"Fetch one rep","description":"One rep by their prefixed id.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The record's prefixed id, as returned in a previous response (for example payout_9d4f2a)."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/periods":{"get":{"operationId":"periods","summary":"List periods","description":"Every commission period this organization has, month, quarter or year. Each carries the timezone its boundaries were decided in, so you can reproduce which side of a boundary a deal fell on.","parameters":[{"name":"starting_after","in":"query","required":false,"schema":{"type":"string"},"description":"Continue the list after this id. Use the next_cursor value from your previous response, or omit it for the first page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"How many records to return. Defaults to 50, and values above 200 are served 200."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/periods/{id}":{"get":{"operationId":"period","summary":"Fetch one period","description":"One period by its prefixed id.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The record's prefixed id, as returned in a previous response (for example payout_9d4f2a)."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/payouts":{"get":{"operationId":"payouts","summary":"List payouts","description":"The current payout for each rep and period, each with its line items: what the rep earned, what was recovered, and what was adjusted. A recalculation replaces a payout rather than editing it, and only the replacement is listed, so summing net_amount over this list gives what is owed once. Amounts are decimal strings and each line names the deal it came from where there is one.","parameters":[{"name":"starting_after","in":"query","required":false,"schema":{"type":"string"},"description":"Continue the list after this id. Use the next_cursor value from your previous response, or omit it for the first page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"How many records to return. Defaults to 50, and values above 200 are served 200."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/payouts/{id}":{"get":{"operationId":"payout","summary":"Fetch one payout","description":"One payout by its prefixed id, with its line items. earned_amount is what the period earned, with anything recovered and any correction to an earlier month already counted, and it is the same amount the rep reads on their own statement. It was called gross_amount before, and that name is not reused. An id stays readable after a recalculation replaces it, and superseded_by_id then names the payout that replaced it. On a current payout superseded_by_id is null.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The record's prefixed id, as returned in a previous response (for example payout_9d4f2a)."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/statements/{id}":{"get":{"operationId":"statement","summary":"Fetch a statement","description":"One payout with the full calculation trace behind it: every step the engine took, in order, with the strategy and version that produced each figure. Takes the payout's id. This is the same trace the rep sees on their own statement.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The record's prefixed id, as returned in a previous response (for example payout_9d4f2a)."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}},"/payroll_files":{"get":{"operationId":"payroll_files","summary":"List payroll records","description":"Money this organization has recorded as having left, one record per rep per period, with the destination it went to. A void is its own record naming the record it reverses, so summing the column gives what was actually paid.","parameters":[{"name":"starting_after","in":"query","required":false,"schema":{"type":"string"},"description":"Continue the list after this id. Use the next_cursor value from your previous response, or omit it for the first page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"How many records to return. Defaults to 50, and values above 200 are served 200."}],"responses":{"401":{"description":"The Authorization header is missing, malformed, or names a key that has been revoked."},"403":{"description":"The key is valid but is not permitted to read. Keys grant read access only."},"404":{"description":"No record with that id is readable by this key."},"400":{"description":"The starting_after value does not name a record this key can read."},"429":{"description":"This key has made too many requests. Retry after the window."},"200":{"description":"The records, under a data key. A list also carries has_more and next_cursor."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Send your key in an Authorization: Bearer header on every request. Keys are per organization, are read-only, and are created and revoked from Settings under API keys."}}}}