Refunds

Name	In	Type	Required	Description
fromDate	query	string(date-time)	false	From datetime used as filter
toDate	query	string(date-time)	false	To datetime used as filter
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription

Request example

1
2
3
4
5



curl -X GET https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/refund?fromDate='2021-10-10T22:00:00Z'&toDate='2021-10-20T22:00:00Z' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Code	Meaning	Description	Schema
200	OK	List of all subscription billing refunds	[RefundResponseDTO]
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Custom schema example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[
  {
    "id": "36d64f0a-71c8-466b-be65-2b0e5adeead5",
    "refund_datetime": "2022-02-24T13:45:10Z",
    "period_start_datetime": "2022-01-31T23:00:00Z",
    "period_end_datetime": "2022-02-28T22:59:59.999999999Z",
    "amount": {
      "value_with_taxes": 12.1,
      "value_without_taxes": 10,
      "tax": {
        "type": "IVA",
        "percentage": 21
      }
    },
    "invoice_id": "987654321",
    "external_invoice_id": "123456789",
    "external_refund_unique_id": "987654321",
    "billable": false,
    "description": "February invoice"
  }
]

Name	Type	Required	Description
id	string	true	none
refund_datetime	string(date-time)	true	none
period_start_datetime	string(date-time)	true	none
period_end_datetime	string(date-time)	true	none
amount	AmountResponseDTO	true	none
invoice_id	string	true	none
external_invoice_id	string	true	none
external_refund_unique_id	string	true	none
billable	boolean	true	none
description	string	true	none

Custom schema example

1
2
3


{
  "error": "subscriptionNotFound"
}

Name	Type	Required	Description
error	string	false	none
message	string	false	none
trace_id	string	false	none

Custom schema example

1
2
3


{
  "error": "getRefundsBySubscription"
}

Name	Type	Required	Description
error	string	false	none
message	string	false	none
trace_id	string	false	none

Custom schema example

1
2
3


{
  "error": "getRefundsBySubscription"
}

Name	Type	Required	Description
error	string	false	none
message	string	false	none
trace_id	string	false	none

Name	In	Type	Required	Description
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription
movementId	path	string	true	Executes the request in the context of the given billing movement

Request example

1
2
3
4
5



curl -X GET https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/movement/eca565cf-8c87-4be5-a189-0a320f5dd1cd/refund \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Code	Meaning	Description	Schema
200	OK	List of all movement billing refunds	[RefundResponseDTO]
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Custom schema example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[
  {
    "id": "36d64f0a-71c8-466b-be65-2b0e5adeead5",
    "refund_datetime": "2022-02-24T13:45:10Z",
    "period_start_datetime": "2022-01-31T23:00:00Z",
    "period_end_datetime": "2022-02-28T22:59:59.999999999Z",
    "amount": {
      "value_with_taxes": 12.1,
      "value_without_taxes": 10,
      "tax": {
        "type": "IVA",
        "percentage": 21
      }
    },
    "invoice_id": "987654321",
    "external_invoice_id": "123456789",
    "external_refund_unique_id": "987654321",
    "billable": false,
    "description": "February invoice"
  }
]

Name	Type	Required	Description
id	string	true	none
refund_datetime	string(date-time)	true	none
period_start_datetime	string(date-time)	true	none
period_end_datetime	string(date-time)	true	none
amount	AmountResponseDTO	true	none
invoice_id	string	true	none
external_invoice_id	string	true	none
external_refund_unique_id	string	true	none
billable	boolean	true	none
description	string	true	none

Custom schema example

1
2
3


{
  "error": "subscriptionNotFound"
}

Name	Type	Required	Description
error	string	false	none
message	string	false	none
trace_id	string	false	none

Custom schema example

1
2
3


{
  "error": "getRefundsByMovement"
}

Name	Type	Required	Description
error	string	false	none
message	string	false	none
trace_id	string	false	none

Custom schema example

1
2
3


{
  "error": "getRefundsByMovement"
}

Name	Type	Required	Description
error	string	false	none
message	string	false	none
trace_id	string	false	none

Create a new billing refund

Create a new billing refund. Refunds can only be created if their related billing movement has been invoiced, that is, if their related billing movement invoice_id field is not empty.

POST /orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund

Parameters

Name	In	Type	Required	Description
body	body	RefundRequestDTO	true	‘none’
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription
movementId	path	string	true	Executes the request in the context of the given billing movement

Request body - instance of RefundRequestDTO

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
  "refund_datetime": "2022-02-24T13:45:10Z",
  "period_start_datetime": "2022-01-31T23:00:00Z",
  "period_end_datetime": "2022-02-28T22:59:59.999999999Z",
  "amount": {
    "value_with_taxes": 12.1,
    "value_without_taxes": 10,
    "tax": {
      "type": "IVA",
      "percentage": 21
    }
  },
  "external_invoice_id": "123456789",
  "external_refund_unique_id": "987654321",
  "billable": false,
  "description": "February invoice"
}

Name	Type	Required	Description
refund_datetime	string(date-time)	true	none
period_start_datetime	string(date-time)	false	none
period_end_datetime	string(date-time)	false	none
amount	AmountRequestDTO	true	none
external_invoice_id	string	false	none
external_refund_unique_id	string	true	none
billable	boolean	true	none
description	string	false	none

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23



curl -X POST https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/movement/eca565cf-8c87-4be5-a189-0a320f5dd1cd/refund \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'refund_datetime': '2022-02-24T13:45:10Z',
  'period_start_datetime': '2022-01-31T23:00:00Z',
  'period_end_datetime': '2022-02-28T22:59:59.999999999Z',
  'amount': {
    'value_with_taxes': 12.1,
    'value_without_taxes': 10,
    'tax': {
      'type': 'IVA',
      'percentage': 21
    }
  },
  'external_invoice_id': '123456789',
  'external_refund_unique_id': '987654321',
  'billable': false,
  'description': 'February invoice'
}" 

Responses

Code	Meaning	Description	Schema
201	Created	Resource created	GenericCreatedResponseDTO
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Get a single billing refund

Retrieves a single billing refund.

GET /orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund/{refundId}

Parameters

Name	In	Type	Required	Description
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription
movementId	path	string	true	Executes the request in the context of the given billing movement
refundId	path	string	true	Executes the request in the context of the given billing refund

Request example

1
2
3
4
5



curl -X GET https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/movement/eca565cf-8c87-4be5-a189-0a320f5dd1cd/refund/36d64f0a-71c8-466b-be65-2b0e5adeead5 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
200	OK	Retrieve a billing refund	RefundResponseDTO
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
404	Not Found	The specified resource was not found	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Update a single billing refund

Update an existing billing refund. Refunds can only be updated if they have not been invoiced, that is, if their invoice_id field is empty.

PUT /orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund/{refundId}

Parameters

Name	In	Type	Required	Description
body	body	RefundRequestDTO	true	‘none’
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription
movementId	path	string	true	Executes the request in the context of the given billing movement
refundId	path	string	true	Executes the request in the context of the given billing refund

Request body - instance of RefundRequestDTO

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
  "refund_datetime": "2022-02-24T13:45:10Z",
  "period_start_datetime": "2022-01-31T23:00:00Z",
  "period_end_datetime": "2022-02-28T22:59:59.999999999Z",
  "amount": {
    "value_with_taxes": 12.1,
    "value_without_taxes": 10,
    "tax": {
      "type": "IVA",
      "percentage": 21
    }
  },
  "external_invoice_id": "123456789",
  "external_refund_unique_id": "987654321",
  "billable": false,
  "description": "February invoice"
}

Name	Type	Required	Description
refund_datetime	string(date-time)	true	none
period_start_datetime	string(date-time)	false	none
period_end_datetime	string(date-time)	false	none
amount	AmountRequestDTO	true	none
external_invoice_id	string	false	none
external_refund_unique_id	string	true	none
billable	boolean	true	none
description	string	false	none

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23



curl -X PUT https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/movement/eca565cf-8c87-4be5-a189-0a320f5dd1cd/refund/36d64f0a-71c8-466b-be65-2b0e5adeead5 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'refund_datetime': '2022-02-24T13:45:10Z',
  'period_start_datetime': '2022-01-31T23:00:00Z',
  'period_end_datetime': '2022-02-28T22:59:59.999999999Z',
  'amount': {
    'value_with_taxes': 12.1,
    'value_without_taxes': 10,
    'tax': {
      'type': 'IVA',
      'percentage': 21
    }
  },
  'external_invoice_id': '123456789',
  'external_refund_unique_id': '987654321',
  'billable': false,
  'description': 'February invoice'
}" 

Responses

Code	Meaning	Description	Schema
204	No Content	Ok with empty body	None
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
404	Not Found	The specified resource was not found	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Delete a single billing refund

Delete an existing billing refund. Refunds can only be deleted if they have not been invoiced, that is, if their invoice_id field is empty.

DELETE /orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund/{refundId}

Parameters

Name	In	Type	Required	Description
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription
movementId	path	string	true	Executes the request in the context of the given billing movement
refundId	path	string	true	Executes the request in the context of the given billing refund

Request example

1
2
3
4
5



curl -X DELETE https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/movement/eca565cf-8c87-4be5-a189-0a320f5dd1cd/refund/36d64f0a-71c8-466b-be65-2b0e5adeead5 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
204	No Content	Ok with empty body	None
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
404	Not Found	The specified resource was not found	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Create a new billing refund (for non subscribable products)

Create a new billing refund (for non subscribable products). Refunds (for non subscribable products) can only be created if their related billing movement has been invoiced, that is, if their related billing movement invoice_id field is not empty.

POST /orgs/{orgId}/subscription/{subscriptionId}/movement/{movementId}/refund-non-subscribable-products

Parameters

Name	In	Type	Required	Description
body	body	RefundNonSubscribableProductsRequestDTO	true	‘none’
orgId	path	string	true	Executes the request in the context of the given organization
subscriptionId	path	string	true	Executes the request in the context of the given subscription
movementId	path	string	true	Executes the request in the context of the given billing movement

Request body - instance of RefundNonSubscribableProductsRequestDTO

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
  "refund_datetime": "2022-02-24T13:45:10Z",
  "period_start_datetime": "2022-01-31T23:00:00Z",
  "period_end_datetime": "2022-02-28T22:59:59.999999999Z",
  "amount": {
    "value_without_taxes": 10
  },
  "external_invoice_id": "123456789",
  "external_refund_unique_id": "987654321",
  "transaction_type_id": "5432167890",
  "description": "February invoice"
}

Name	Type	Required	Description
refund_datetime	string(date-time)	true	none
period_start_datetime	string(date-time)	false	none
period_end_datetime	string(date-time)	false	none
amount	BillableAmountRequestDTO	true	none
external_invoice_id	string	false	none
external_refund_unique_id	string	false	none
transaction_type_id	string	true	none
description	string	false	none

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18



curl -X POST https://billing.masstack.com/v1/orgs/masmovil/subscription/123456789/movement/eca565cf-8c87-4be5-a189-0a320f5dd1cd/refund-non-subscribable-products \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'refund_datetime': '2022-02-24T13:45:10Z',
  'period_start_datetime': '2022-01-31T23:00:00Z',
  'period_end_datetime': '2022-02-28T22:59:59.999999999Z',
  'amount': {
    'value_without_taxes': 10
  },
  'external_invoice_id': '123456789',
  'external_refund_unique_id': '987654321',
  'transaction_type_id': '5432167890',
  'description': 'February invoice'
}" 

Responses

Code	Meaning	Description	Schema
201	Created	Resource created	GenericCreatedResponseDTO
400	Bad Request	The request could not be processed because it was malformed	GenericResponseDTO
401	Unauthorized	The user is not authorized	GenericResponseDTO
403	Forbidden	The user does not have permission to access that resource	GenericResponseDTO
500	Internal Server Error	The request failed to be processed by the server	GenericResponseDTO
502	Bad Gateway	A third party connection is not responding	GenericResponseDTO
504	Gateway Time-out	The request timed out	GenericResponseDTO

Refunds

Get a list of all billing refunds, related to a subscription

Parameters

Request example

Responses

200 - instance of RefundResponseDTO

400 - instance of GenericResponseDTO

500 - instance of GenericResponseDTO

502 - instance of GenericResponseDTO

Get a list of all billing refunds, related to a billing movement

Parameters

Request example

Responses

200 - instance of RefundResponseDTO

400 - instance of GenericResponseDTO

500 - instance of GenericResponseDTO

502 - instance of GenericResponseDTO

Create a new billing refund

Parameters

Request body - instance of RefundRequestDTO

Request example

Responses

Get a single billing refund

Parameters

Request example

Responses

Update a single billing refund

Parameters

Request body - instance of RefundRequestDTO

Request example

Responses

Delete a single billing refund

Parameters

Request example

Responses

Create a new billing refund (for non subscribable products)

Parameters

Request body - instance of RefundNonSubscribableProductsRequestDTO

Request example

Responses