openapi: 3.2.0 info: title: Endpoints Credit notes API version: v1 servers: - url: https://api.oysterhr.com description: Production server - url: https://api-sandbox.oysterhr.com description: Sandbox server tags: - name: Credit notes paths: /v1/credit_notes: get: summary: Retrieve all credit notes tags: - Credit notes description: Returns company's credit notes security: - bearer_auth: - read parameters: - name: per_page in: query required: false schema: type: integer - name: reference_codes[] in: query required: false description: Filter by reference codes schema: type: array items: type: string - name: payroll_period_from in: query required: false description: Filter by payroll period start date (YYYY-MM format) schema: type: string - name: payroll_period_to in: query required: false description: Filter by payroll period end date (YYYY-MM format) schema: type: string - name: from_issue_date in: query required: false description: Filter by issue date start (YYYY-MM-DD format) schema: type: string - name: to_issue_date in: query required: false description: Filter by issue date end (YYYY-MM-DD format) schema: type: string - name: types[] in: query required: false description: Filter by credit note types schema: type: array items: enum: - MANUAL - PREFUNDING_REFUND - CLOSING_INVOICE_REFUND - DEPOSIT_REFUND - CREDIT_ADJUSTMENT - SCALE_REFUND - SALARY_INSIGHTS_REFUND - GLOBAL_PAYROLL_REFUND - name: statuses[] in: query required: false description: Filter by credit note statuses schema: type: array items: enum: - ISSUED - REFUNDED - APPLIED - PARTIALLY_APPLIED - VOIDED responses: '200': description: Successful content: application/json: examples: No credit notes: value: data: [] meta: items: 100 count: 0 page: 1 pages: 1 firstUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page=1 lastUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page=1 pageUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page=1 nextUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page= prevUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page= Successful: value: data: - id: C717531e referenceCode: OY-IMPA-ANNA-D8cac3f5-50c8d9-CN type: MANUAL status: ISSUED payrollMonth: '10' payrollYear: '2022' issueDate: '2022-10-15T00:00:00Z' totalAmount: decimal: '123.00' currencyCode: USD amountRemaining: decimal: '123.00' currencyCode: USD - id: Bd77da0d referenceCode: OY-IMPA-ANNA-C33471b0-cf73ee-CN type: MANUAL status: ISSUED payrollMonth: '10' payrollYear: '2022' issueDate: '2022-10-15T00:00:00Z' totalAmount: decimal: '123.00' currencyCode: USD amountRemaining: decimal: '123.00' currencyCode: USD - id: A74e749c referenceCode: OY-IMPA-ANNA-B7875a51-28c38a-CN type: MANUAL status: ISSUED payrollMonth: '10' payrollYear: '2022' issueDate: '2022-10-15T00:00:00Z' totalAmount: decimal: '123.00' currencyCode: USD amountRemaining: decimal: '123.00' currencyCode: USD meta: items: 100 count: 3 page: 1 pages: 1 firstUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page=1 lastUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page=1 pageUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page=1 nextUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page= prevUrl: /v1/credit_notes?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&fromIssueDate=&toIssueDate=&page= schema: type: object properties: data: $ref: '#/components/schemas/creditNotes' meta: $ref: '#/components/schemas/meta' required: - data - meta operationId: getV1CreditNotes x-operation-id-source: derived /v1/credit_notes/sources/statuses: get: summary: Retrieve credit notes rulesets for source statuses tags: - Credit notes description: Returns data on the statuses of credit notes available, including the value identifier and the corresponding title for each credit note status security: - bearer_auth: - read responses: '200': description: Successfully retrieve source statuses content: application/json: examples: Successfully retrieve source statuses: value: data: - value: ISSUED title: Issued - value: REFUNDED title: Refunded - value: APPLIED title: Applied - value: PARTIALLY_APPLIED title: Partially Applied - value: VOIDED title: Voided schema: type: object properties: data: $ref: '#/components/schemas/sourceOptions' required: - data operationId: getV1CreditNotesSourcesStatuses x-operation-id-source: derived /v1/credit_notes/sources/types: get: summary: Retrieve credit notes rulesets for source types tags: - Credit notes description: Returns data on the types of credit notes available, including the value identifier and the corresponding title for each credit note type security: - bearer_auth: - read responses: '200': description: Successfully retrieve source types content: application/json: examples: Successfully retrieve source types: value: data: - value: MANUAL title: Manual - value: PREFUNDING_REFUND title: Prefunding Refund - value: CLOSING_INVOICE_REFUND title: Closing Invoice Refund - value: DEPOSIT_REFUND title: Deposit Refund - value: CREDIT_ADJUSTMENT title: Credit Adjustment - value: SCALE_REFUND title: Scale Refund - value: SALARY_INSIGHTS_REFUND title: Salary Insights Refund - value: GLOBAL_PAYROLL_REFUND title: Global Payroll Refund schema: type: object properties: data: $ref: '#/components/schemas/sourceOptions' required: - data operationId: getV1CreditNotesSourcesTypes x-operation-id-source: derived /v1/credit_notes/{identifier}: get: summary: Retrieve a credit note tags: - Credit notes description: Returns a credit note security: - bearer_auth: - read parameters: - name: identifier in: path description: Credit note ID or Reference Code required: true schema: type: string responses: '200': description: Successfully retrieves customer for credit note content: application/json: examples: Successfully retrieve credit note: value: data: id: A74e749c referenceCode: OY-IMPA-ANNA-B7875a51-13b0d0-CN type: MANUAL status: ISSUED payrollMonth: '10' payrollYear: '2022' issueDate: '2022-10-15T00:00:00Z' totalAmount: decimal: '100.00' currencyCode: USD amountRemaining: decimal: '100.00' currencyCode: USD files: document: title: file url: http://api.example.com/83ca06bb5063276c088b5ebb85bced3a/document.pdf contentType: application/pdf appliedToInvoices: - id: Ade9533d referenceCode: OY-IMPA-ANNA-D8cac3f5-331 amount: decimal: '520.00' currencyCode: USD appliedAt: '2022-10-15T12:34:56Z' - id: B94181b5 referenceCode: OY-IMPA-ANNA-E780e616-3a8 amount: decimal: '1000.00' currencyCode: USD appliedAt: '2022-10-15T12:34:56Z' Successfully retrieves customer for credit note: value: data: id: A74e749c referenceCode: OY-IMPA-ANNA-B7875a51-54affa-CN type: MANUAL status: DRAFT payrollMonth: '10' payrollYear: '2022' issueDate: '2022-10-15T00:00:00Z' totalAmount: decimal: '123.00' currencyCode: USD amountRemaining: decimal: '123.00' currencyCode: USD customer: id: B7875a51 name: company 00002 name files: document: title: file url: http://api.example.com/83ca06bb5063276c088b5ebb85bced3a/document.pdf contentType: application/pdf appliedToInvoices: - id: Ade9533d referenceCode: OY-IMPA-ANNA-C33471b0-aa7 amount: decimal: '520.00' currencyCode: USD appliedAt: '2022-10-15T12:34:56Z' - id: B94181b5 referenceCode: OY-IMPA-ANNA-D8cac3f5-906 amount: decimal: '1000.00' currencyCode: USD appliedAt: '2022-10-15T12:34:56Z' schema: type: object properties: data: $ref: '#/components/schemas/creditNote' required: - data operationId: getV1CreditNotesByIdentifier x-operation-id-source: derived components: schemas: sourceOptions: type: array items: $ref: '#/components/schemas/sourceOption' meta: type: object properties: items: type: integer count: type: integer page: type: integer pages: type: integer firstUrl: type: string lastUrl: type: string pageUrl: type: string nextUrl: type: string prevUrl: type: string deprecation: type: object properties: at: type: string sunset: type: string link: type: object properties: rel: type: string url: type: string required: - items - count - page - pages - firstUrl - lastUrl - pageUrl - nextUrl - prevUrl creditNote: type: object required: - id - referenceCode - type - status - payrollMonth - payrollYear - issueDate - totalAmount - amountRemaining properties: id: type: string referenceCode: type: string type: type: string status: type: string payrollMonth: type: string payrollYear: type: string issueDate: type: string format: date totalAmount: $ref: '#/components/schemas/amount' amountRemaining: $ref: '#/components/schemas/amount' customer: type: object required: - id - name properties: id: type: string name: type: string files: type: - object - 'null' required: - document properties: document: type: object required: - title - url - contentType properties: title: type: string url: type: string contentType: type: string appliedToInvoices: type: - array - 'null' items: type: object required: - id - referenceCode - appliedAt - amount properties: id: type: string referenceCode: type: string amount: $ref: '#/components/schemas/amount' appliedAt: type: string format: date-time creditNotes: type: array items: $ref: '#/components/schemas/creditNote' sourceOption: type: object properties: value: type: string title: type: string required: - value - title amount: type: object properties: decimal: type: string pattern: ^\d+([.]\d+)?$ currencyCode: type: string minLength: 3 maxLength: 3 required: - decimal - currencyCode securitySchemes: bearer_auth: type: http scheme: bearer x-provenance: method: searched source: https://docs.oysterhr.com/reference harvested: '2026-10-14' tool: harvest-readme-openapi.py note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored. assembled_from: - https://docs.oysterhr.com/reference/delete_v1-bank-accounts-id.md - https://docs.oysterhr.com/reference/delete_v1-consent-grants.md - https://docs.oysterhr.com/reference/delete_v1-expenses-id.md - https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-commission-plan.md - https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-document-document-id.md - https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-work-permit.md - https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id.md - https://docs.oysterhr.com/reference/delete_v1-payments-charge-groups-id-wire-sent.md - https://docs.oysterhr.com/reference/delete_v1-payroll-changes-id.md - https://docs.oysterhr.com/reference/delete_v1-time-tracking-time-sheets-entries-id.md - https://docs.oysterhr.com/reference/delete_v1-time-tracking-time-sheets-id.md - https://docs.oysterhr.com/reference/delete_v1-webhooks-id.md - https://docs.oysterhr.com/reference/get_v1-bank-accounts-id.md - https://docs.oysterhr.com/reference/get_v1-bank-accounts-rulesets.md - https://docs.oysterhr.com/reference/get_v1-bank-accounts.md - https://docs.oysterhr.com/reference/get_v1-benefits-engagements-engagement-id-offerings.md - https://docs.oysterhr.com/reference/get_v1-benefits-enrollments-id.md - https://docs.oysterhr.com/reference/get_v1-benefits-ruleset.md - https://docs.oysterhr.com/reference/get_v1-company.md - https://docs.oysterhr.com/reference/get_v1-contract-changes-id.md - https://docs.oysterhr.com/reference/get_v1-contract-changes-rulesets.md - https://docs.oysterhr.com/reference/get_v1-contract-changes.md - https://docs.oysterhr.com/reference/get_v1-credit-notes-identifier.md - https://docs.oysterhr.com/reference/get_v1-credit-notes-sources-statuses.md - https://docs.oysterhr.com/reference/get_v1-credit-notes-sources-types.md - https://docs.oysterhr.com/reference/get_v1-credit-notes.md - https://docs.oysterhr.com/reference/get_v1-departments.md - https://docs.oysterhr.com/reference/get_v1-engagements-id-allowances.md - https://docs.oysterhr.com/reference/get_v1-engagements-id-bonuses.md - https://docs.oysterhr.com/reference/get_v1-engagements-id-documents.md - https://docs.oysterhr.com/reference/get_v1-engagements-id-identity-verification.md - https://docs.oysterhr.com/reference/get_v1-engagements-id-payslips.md - https://docs.oysterhr.com/reference/get_v1-engagements-id.md - https://docs.oysterhr.com/reference/get_v1-engagements.md - https://docs.oysterhr.com/reference/get_v1-expenses-id.md - https://docs.oysterhr.com/reference/get_v1-expenses-ruleset.md - https://docs.oysterhr.com/reference/get_v1-expenses-rulesets-id-sources-categories.md - https://docs.oysterhr.com/reference/get_v1-expenses-rulesets-id.md - https://docs.oysterhr.com/reference/get_v1-expenses.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-agreements-agreement-id.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-agreements.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-cost-estimates-annually.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-cost-estimates-monthly.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-onboarding-form-documents-field-or-document-id.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-onboarding-form.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-tasks.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-id.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-onboarding-form.md - https://docs.oysterhr.com/reference/get_v1-hiring-employments-rulesets.md - https://docs.oysterhr.com/reference/get_v1-hiring-role-types.md - https://docs.oysterhr.com/reference/get_v1-invoices-identifier-breakdown.md - https://docs.oysterhr.com/reference/get_v1-invoices-identifier.md - https://docs.oysterhr.com/reference/get_v1-invoices-sources-statuses.md - https://docs.oysterhr.com/reference/get_v1-invoices-sources-types.md - https://docs.oysterhr.com/reference/get_v1-invoices.md - https://docs.oysterhr.com/reference/get_v1-meta-operations-operation-key.md - https://docs.oysterhr.com/reference/get_v1-offboardings-id-agreements.md - https://docs.oysterhr.com/reference/get_v1-offboardings-id.md - https://docs.oysterhr.com/reference/get_v1-offboardings-payroll-team-members-terminations-rulesets.md - https://docs.oysterhr.com/reference/get_v1-offboardings-sources-employment-type-categories.md - https://docs.oysterhr.com/reference/get_v1-offboardings-sources-employment-type-pay-types.md - https://docs.oysterhr.com/reference/get_v1-offboardings.md - https://docs.oysterhr.com/reference/get_v1-payments-charge-groups-id-charges.md - https://docs.oysterhr.com/reference/get_v1-payments-charge-groups-id.md - https://docs.oysterhr.com/reference/get_v1-payments-charge-groups.md - https://docs.oysterhr.com/reference/get_v1-payments-charges-id.md - https://docs.oysterhr.com/reference/get_v1-payments-payouts-id.md - https://docs.oysterhr.com/reference/get_v1-payroll-changes-id.md - https://docs.oysterhr.com/reference/get_v1-payroll-changes-ruleset.md - https://docs.oysterhr.com/reference/get_v1-payroll-changes-rulesets-default-sources-types.md - https://docs.oysterhr.com/reference/get_v1-payroll-changes-rulesets-default.md - https://docs.oysterhr.com/reference/get_v1-payroll-changes-sources-types.md - https://docs.oysterhr.com/reference/get_v1-payroll-changes.md - https://docs.oysterhr.com/reference/get_v1-payroll-id-records.md - https://docs.oysterhr.com/reference/get_v1-payroll-id.md - https://docs.oysterhr.com/reference/get_v1-payroll.md - https://docs.oysterhr.com/reference/get_v1-public-holidays.md - https://docs.oysterhr.com/reference/get_v1-reseller-customers.md - https://docs.oysterhr.com/reference/get_v1-time-off-entitlements-id.md - https://docs.oysterhr.com/reference/get_v1-time-off-entitlements.md - https://docs.oysterhr.com/reference/get_v1-time-off-requests-id.md - https://docs.oysterhr.com/reference/get_v1-time-off-requests.md - https://docs.oysterhr.com/reference/get_v1-time-tracking-rulesets-engagement-id-sources-source-type.md - https://docs.oysterhr.com/reference/get_v1-time-tracking-rulesets-engagement-id.md - https://docs.oysterhr.com/reference/get_v1-time-tracking-time-sheets-id.md - https://docs.oysterhr.com/reference/get_v1-time-tracking-time-sheets.md - https://docs.oysterhr.com/reference/get_v1-webhooks-dispatches.md - https://docs.oysterhr.com/reference/get_v1-webhooks.md - https://docs.oysterhr.com/reference/patch_v1-bank-accounts-id.md - https://docs.oysterhr.com/reference/patch_v1-employments-id-personal-details.md - https://docs.oysterhr.com/reference/patch_v1-hiring-employments-id-onboarding-form.md - https://docs.oysterhr.com/reference/patch_v1-hiring-employments-id.md - https://docs.oysterhr.com/reference/patch_v1-payroll-changes-id.md - https://docs.oysterhr.com/reference/patch_v1-reseller-customers-id.md - https://docs.oysterhr.com/reference/patch_v1-time-tracking-time-sheets-entries-id.md - https://docs.oysterhr.com/reference/patch_v1-webhooks-id.md - https://docs.oysterhr.com/reference/post_v1-bank-accounts.md - https://docs.oysterhr.com/reference/post_v1-benefits-engagements-engagement-id-enrollments.md - https://docs.oysterhr.com/reference/post_v1-consent-grants.md - https://docs.oysterhr.com/reference/post_v1-contract-changes-id-cancel.md - https://docs.oysterhr.com/reference/post_v1-contract-changes.md - https://docs.oysterhr.com/reference/post_v1-engagements-id-identity-verification-approved.md - https://docs.oysterhr.com/reference/post_v1-engagements-id-identity-verification-declined.md - https://docs.oysterhr.com/reference/post_v1-engagements-id-identity-verification-sessions.md - https://docs.oysterhr.com/reference/post_v1-expenses-id-approve.md - https://docs.oysterhr.com/reference/post_v1-expenses-id-decline.md - https://docs.oysterhr.com/reference/post_v1-expenses.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-agreements-agreement-id-verify.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-commission-plan.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-document.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-onboarding-form-complete.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-submit.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-team-member-invite.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-work-permit.md - https://docs.oysterhr.com/reference/post_v1-hiring-employments.md - https://docs.oysterhr.com/reference/post_v1-invoices-identifier-approve.md - https://docs.oysterhr.com/reference/post_v1-invoices-identifier-dispute.md - https://docs.oysterhr.com/reference/post_v1-offboardings-contractors-resignations.md - https://docs.oysterhr.com/reference/post_v1-offboardings-contractors-terminations.md - https://docs.oysterhr.com/reference/post_v1-offboardings-employments-resignations.md - https://docs.oysterhr.com/reference/post_v1-offboardings-employments-terminations.md - https://docs.oysterhr.com/reference/post_v1-offboardings-id-cancellation.md - https://docs.oysterhr.com/reference/post_v1-offboardings-id-documents.md - https://docs.oysterhr.com/reference/post_v1-offboardings-id-initiate.md - https://docs.oysterhr.com/reference/post_v1-offboardings-payroll-team-members-terminations.md - https://docs.oysterhr.com/reference/post_v1-payments-charge-groups-id-wire-sent.md - https://docs.oysterhr.com/reference/post_v1-payroll-changes.md - https://docs.oysterhr.com/reference/post_v1-reseller-customers.md - https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-approve.md - https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-attachment.md - https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-cancel.md - https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-reject.md - https://docs.oysterhr.com/reference/post_v1-time-off-requests.md - https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets-entries.md - https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets-id-confirm.md - https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets-id-submit.md - https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets.md - https://docs.oysterhr.com/reference/post_v1-webhooks-id-test.md - https://docs.oysterhr.com/reference/post_v1-webhooks.md - https://docs.oysterhr.com/reference/put_v1-hiring-employments-id-onboarding-form-documents-field-id.md merge: pages: 140 deduped: 378 conflicts_kept_first: 0