info: title: Ows-accounting API specifications version: 1.0.0 host: qa-ows-accounting.theorchard.io schemes: - https swagger: '2.0' parameters: 'trait:grassHeaders:Grass-Account-Type': description: Grass account type enum: - vendor - subaccount type: string in: header name: Grass-Account-Type required: true 'trait:grassHeaders:Grass-Account-Id': pattern: ^\d+$ description: Grass account id type: string in: header name: Grass-Account-Id required: true 'trait:userIdHeaders:Orchard-User-Id': pattern: '^(oa:|alw:)\d+$' description: Orchard user id type: string in: header name: Orchard-User-Id required: true 'trait:accountQueryParameters:account_type': description: Account type enum: - vendor - subaccount type: string in: query name: account_type required: true 'trait:accountQueryParameters:account_id': pattern: ^\d+$ description: Account id type: string in: query name: account_id required: true 'trait:paginationQueryParameters:page_offset': default: 0 description: 'Corresponds to page number, starting with 0' type: number in: query name: page_offset required: true 'trait:paginationQueryParameters:page_limit': default: 50 description: Max items per page type: number in: query name: page_limit required: true paths: /: get: description: Says hello operationId: GET_root produces: - text/plain responses: '200': description: '' schema: example: | Hello John! parameters: - description: Name to say hello type: string in: query name: name required: true /hello: get: operationId: GET_hello produces: - application/json responses: '200': description: '' schema: example: status: ok '500': description: '' schema: example: code: internal_error message: Could not connect to database /reports: get: description: >- Retrieve reports for statement period and account specified by query params operationId: GET_reports produces: - application/json responses: '200': description: 200 OK schema: example: items: - generation_start: '2017-01-01 10:00:00' requested_by: Somebody period_ids: '100,101,102' transaction_types: 'AEA,AEV,AL' file_type: txt number_format: us s3_url: 's3://public.theorchard.com/reports/111' status: GENERATED - generation_start: '2017-01-02 16:00:00' requested_by: John Doe period_ids: '103,104,105' transaction_types: all file_type: txt number_format: us s3_url: 's3://public.theorchard.com/reports/200' status: GENERATED pagination: type: standard offset: 0 limit: 50 total_records: 10 '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true pattern: '(^[0-9]+$)|(^([0-9])+(,[0-9]+)+$)' description: Comma-delimited set of period ids corresponding to Statement Period type: string in: query name: periods - $ref: '#/parameters/trait:accountQueryParameters:account_type' - $ref: '#/parameters/trait:accountQueryParameters:account_id' - $ref: '#/parameters/trait:paginationQueryParameters:page_offset' - $ref: '#/parameters/trait:paginationQueryParameters:page_limit' /report: get: description: Retrieve report specified by query params operationId: GET_report produces: - application/json responses: '302': description: '' headers: Access-Control-Allow-Origin: type: string Location: description: URL type: string '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '404': description: 404 Not Found schema: example: code: not_found_error message: >- S3 object for path: s3://public.theorchard.com/reports/111 not found. '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true pattern: '(^[0-9]+$)|(^([0-9])+(,[0-9]+)+$)' description: Comma-delimited set of period ids corresponding to Statement Period type: string in: query name: periods - required: true pattern: '(^\w+$)|(^(\w)+(,\w+)+$)' description: Comma-delimited set of transaction types for requested report type: string in: query name: transaction_types - required: true pattern: ^(en_US|es_ES)$ description: Number format of requested report type: string in: query name: number_format - required: true pattern: ^(txt|xls|TXT|XLS)$ maxLength: 255 description: File type of requested report type: string in: query name: file_type - $ref: '#/parameters/trait:accountQueryParameters:account_type' - $ref: '#/parameters/trait:accountQueryParameters:account_id' post: description: >- Request to create a new report for the statement period and additional provided params operationId: POST_report produces: - application/json responses: '200': description: Report was successfuly created '302': description: Report is generating '304': description: Report was generated '400': description: Source data not available schema: example: message: Source data not available '409': description: Workflow already executed schema: example: code: workflow_executed_already message: Error Message '500': description: '' schema: example: code: internal_error message: Could not connect to database consumes: - application/json parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - schema: type: object properties: periods: pattern: '(^[0-9]+$)|(^([0-9])+(,[0-9]+)+$)' description: >- Comma-delimited set of period ids corresponding to Statement Period type: string transaction_types: pattern: '(^\w+$)|(^(\w)+(,\w+)+$)' description: Comma-delimited set of transaction types for requested report type: string number_format: pattern: ^(en_US|es_ES)$ minLength: 1 description: Number format of requested report type: string file_type: pattern: ^(txt|xls|TXT|XLS)$ minLength: 1 maxLength: 255 description: File type of requested report type: string request_context: description: >- A JSON Hash containing available attributes from Workstation that describe request context type: object properties: contact_id: description: Workstations contact id type: integer contact_email: description: Workstation contact email type: string first_name: description: Workstation contact first name type: string last_name: description: Workstation contact last name type: string required: - contact_id - contact_email - first_name - last_name required: - periods - transaction_types - number_format - file_type - request_context in: body name: body required: true /transaction_types: get: description: >- Retrieve set of relevant transaction types for the account and requested statement period operationId: GET_transaction_types produces: - application/json responses: '200': description: 200 OK schema: example: items: - short_name: AEA long_name: Ad-Enabled Audio Streams - short_name: AEV long_name: Ad-Enabled Video Streams '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true pattern: '(^[0-9]+$)|(^([0-9])+(,[0-9]+)+$)' description: Comma-delimited set of period ids corresponding to Statement Period type: string in: query name: periods /revenue: get: description: Getting account revenue operationId: GET_revenue produces: - application/json responses: '200': description: 200 OK schema: example: items: - min_accounting_period: 101 max_accounting_period: 101 interval: type: month number: 1 year: 2016 currency_id: 1 currency_symbol: '$' revenue: 100.55 num_transactions: 15 - min_accounting_period: 102 max_accounting_period: 104 interval: type: quarter number: 3 year: 2016 currency_id: 1 currency_symbol: '$' revenue: 10410.11 num_transactions: 221 '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '404': description: 404 Not Found schema: example: code: '' message: Accounting period not found '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true minimum: 1 description: Number of recent accounting intervals for revenue calculation type: integer in: query name: recent /payments: get: description: Getting account payments information operationId: GET_payments produces: - application/json responses: '200': description: 200 OK schema: example: items: - min_accounting_period: 101 max_accounting_period: 101 interval: type: month number: 1 year: 2016 currency_id: 1 currency_symbol: '$' payment: 682.24 - min_accounting_period: 102 max_accounting_period: 104 interval: type: quarter number: 3 year: 2016 currency_id: 1 currency_symbol: '$' payment: 99999.99 '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '404': description: 404 Not Found schema: example: code: '' message: Accounting period not found '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true minimum: 1 description: Number of recent accounting intervals for payments calculation type: integer in: query name: recent /holds/active: get: description: Gets all active holds in our system. operationId: GET_holds-active produces: - application/json responses: '200': description: 200 OK schema: example: pagination: type: none total_records: 2 items: - status: active vendor_payment_hold_log: [] hold_id: 1 last_updated: '2017-06-05T03:33:53' vendor_id: 17295 created_time: '2017-06-05T03:33:53' creator_id: 'oa:1354' description: test hold 17295 - status: active vendor_payment_hold_log: [] hold_id: 10 last_updated: '2017-06-06T06:13:04' vendor_id: 2624 created_time: '2017-06-06T06:12:07' creator_id: 'oa:66' description: desc amit parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - $ref: '#/parameters/trait:userIdHeaders:Orchard-User-Id' '/holds/{hold_id}': get: description: Gets a specific hold. operationId: GET_holds-hold_id produces: - application/json responses: '200': description: 200 OK schema: example: status: inactive hold_id: 4 last_updated: '2017-06-06T05:19:39' vendor_id: 25296 created_time: '2017-06-05T04:15:05' creator_id: 'oa:1354' description: 'Tax levy in the amount of $282.18 ' vendor_payment_hold_log: - user_id: 'oa:1354' timestamp: '2017-06-05T04:15:05' status: active action: create description: hold1 - user_id: 'oa:562' timestamp: '2017-06-06T05:19:39' status: inactive action: update description: 'Tax levy in the amount of $282.18 ' '404': description: '' schema: example: code: not_found_error message: No hold found with this id. parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - $ref: '#/parameters/trait:userIdHeaders:Orchard-User-Id' put: description: Updates a specific hold. operationId: PUT_holds-hold_id produces: - application/json responses: '200': description: 200 OK schema: example: status: active vendor_payment_hold_log: - user_id: 'oa:123' timestamp: '2017-06-07T07:47:52' status: active action: create description: This vendor is on hold because xyz. - user_id: 'oa:123' timestamp: '2017-06-07T07:49:56' status: active action: update description: desc updated. hold_id: 44 last_updated: '2017-06-07T07:49:56' vendor_id: 7124 created_time: '2017-06-07T07:47:52' creator_id: 'oa:123' description: desc updated. '400': description: 400 Bad Request schema: example: code: invalid_request_error message: Missing required params. '404': description: '' schema: example: code: invalid_request_error message: Missing required params. consumes: - application/json parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - $ref: '#/parameters/trait:userIdHeaders:Orchard-User-Id' - schema: example: status: active description: desc updated. properties: status: description: Status of hold. type: string description: description: Reason for the hold. type: string required: - status type: object in: body name: body required: true parameters: - type: string in: path name: hold_id required: true '/holds/vendor/{vendor_id}': post: description: Create a new hold for a vendor. operationId: POST_holds-vendor-vendor_id produces: - application/json responses: '200': description: 200 OK schema: example: status: active hold_id: 44 last_updated: '2017-06-07T07:47:52' vendor_id: 7124 created_time: '2017-06-07T07:47:52' creator_id: 'oa:123' description: This vendor is on hold because xyz. vendor_payment_hold_log: - user_id: 'oa:123' timestamp: '2017-06-07T07:47:52' status: active action: create description: This vendor is on hold because xyz. '400': description: 400 Bad Request schema: example: code: invalid_request_error message: Missing required params. '404': description: '' schema: example: code: not_found_error message: No vendor found with this id. consumes: - application/json parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - $ref: '#/parameters/trait:userIdHeaders:Orchard-User-Id' - schema: example: status: active description: This vendor is on hold because xyz. properties: status: description: Status of hold. type: string description: description: Reason for the hold. type: string required: - status type: object in: body name: body required: true get: description: Gets all holds for a vendor. operationId: GET_holds-vendor-vendor_id produces: - application/json responses: '200': description: 200 OK schema: example: items: - status: inactive vendor_payment_hold_log: [] hold_id: 24 last_updated: '2017-06-06T09:40:54' vendor_id: 7123 created_time: '2017-06-06T09:40:54' creator_id: 'oa:562' description: '' - status: inactive vendor_payment_hold_log: [] hold_id: 27 last_updated: '2017-06-07T06:57:50' vendor_id: 7123 created_time: '2017-06-06T10:30:56' creator_id: 'oa:1485' description: Add new 1234 - status: active vendor_payment_hold_log: [] hold_id: 43 last_updated: '2017-06-07T07:04:34' vendor_id: 7123 created_time: '2017-06-07T07:04:22' creator_id: 'oa:562' description: Test12 pagination: type: none total_records: 3 '404': description: '' schema: example: code: not_found_error message: No vendor found with this vendor_id. parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - $ref: '#/parameters/trait:userIdHeaders:Orchard-User-Id' parameters: - type: string in: path name: vendor_id required: true /accounting_period: get: description: Getting active accounting period operationId: GET_accounting_period produces: - application/json responses: '200': description: 200 OK schema: example: accounting_period: 123 '500': description: '' schema: example: code: internal_error message: Could not connect to database /eq_bonus: get: description: >- Retrieve summary of Spotify EQ bonus for the account operationId: GET_eq_bonus produces: - application/json responses: '200': description: 200 OK schema: example: eq_bonus: 1233.99 usd_eq_bonus: 1222.99 currency_html_symbol: £ '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true pattern: '(^[0-9]+$)' description: Period id corresponding to Statement Period type: string in: query name: period_id /eq_bonus_payment: get: description: >- Retrieve details of Spotify EQ bonus payment for the account operationId: GET_eq_bonus produces: - application/json responses: '200': description: 200 OK schema: example: amount: 1233.99 currency_html_symbol: £ check_no: 'Spotify Equity Payment SP PAYOUT' date: '01/15/2018' comments: 'Check comments' '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '500': description: '' schema: example: code: internal_error message: Could not connect to database parameters: - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Type' - $ref: '#/parameters/trait:grassHeaders:Grass-Account-Id' - required: true pattern: '(^[0-9]+$)' description: Period id corresponding to Statement Period type: string in: query name: period_id /{account_type}/{account_id}/average-monthly-net-revenue: get: description: Get the average monthly net revenue for a vendor or a subaccount parameters: - in: path name: account_type required: true type: string enum: - vendor - subaccount - in: path name: account_id required: true type: number - in: header name: Grass-Account-Type type: string - in: header name: Grass-Account-Id type: number responses: '200': description: 200 OK schema: type: object properties: average_monthly_net_revenue: type: number '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '500': description: 500 Internal Error schema: example: code: internal_error message: Could not connect to database /get-physical-reserves: get: description: Get physical reserves information for a vendor parameters: - in: path name: vendor_id required: true type: number - in: path name: period_id required: true type: number - in: header name: Grass-Account-Type type: string - in: header name: Grass-Account-Id type: number responses: '200': description: 200 OK schema: example: - reserve_taken_date: 'Jan 2019' reserve_release_date: 'Jul 2019' currency: 'USD' amount: '100.00' - reserve_taken_date: 'Feb 2019' reserve_release_date: 'Aug 2019' currency: 'GBP' amount: '50' '400': description: 400 Bad Request schema: example: code: bad_grass_request_error message: Incomplete Grass Headers '403': description: 403 Forbidden schema: example: code: authorization_error message: User is forbidden '500': description: 500 Internal Error schema: example: code: internal_error message: Could not connect to database