Skip to content

Commit

Permalink
[DE-801] Fix invoice events structure #25
Browse files Browse the repository at this point in the history
- Remove default collection method value
- Reorganize `Invoice Event` structure:
  - Invoice Event is now union type
  - Invoice Event Data is no longer union type. Each Invoice Event has it's own invoice_data with a concrete type
- Remove some redundant models
- Set usage ids, events ids and invoice event ids as longs,
- Set Invoice Event id to long
- Add new invoice event data types
- Add handle parameter for create product family request body
- Add in_use query parameter for listing subscription components
  • Loading branch information
maciej-nedza authored Jun 5, 2024
2 parents d9911de + a3e9824 commit f7506c5
Show file tree
Hide file tree
Showing 126 changed files with 3,763 additions and 2,718 deletions.
2 changes: 1 addition & 1 deletion advance_invoice_controller.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ func NewAdvanceInvoiceController(baseController baseController) *AdvanceInvoiceC
// IssueAdvanceInvoice takes context, subscriptionId, body as parameters and
// returns an models.ApiResponse with models.Invoice data and
// an error if there was an issue with the request or response.
// Generate an invoice in advance for a subscription's next renewal date. [Please see our docs](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404811062541-Issue-Invoice-In-Advance ) for more information on advance invoices, including eligibility on generating one; for the most part, they function like any other invoice, except they are issued early and have special behavior upon being voided.
// Generate an invoice in advance for a subscription's next renewal date. [Please see our docs](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404811062541-Issue-Invoice-In-Advance) for more information on advance invoices, including eligibility on generating one; for the most part, they function like any other invoice, except they are issued early and have special behavior upon being voided.
// A subscription may only have one advance invoice per billing period. Attempting to issue an advance invoice when one already exists will return an error.
// That said, regeneration of the invoice may be forced with the params `force: true`, which will void an advance invoice if one exists and generate a new one. If no advance invoice exists, a new one will be generated.
// We recommend using either the create or preview endpoints for proforma invoices to preview this advance invoice before using this endpoint to generate it.
Expand Down
12 changes: 6 additions & 6 deletions doc/controllers/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,8 @@ ListEvents(
| --- | --- | --- | --- |
| `page` | `*int` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.<br>Use in query `page=1`. |
| `perPage` | `*int` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.<br>Use in query `per_page=200`. |
| `sinceId` | `*int` | Query, Optional | Returns events with an id greater than or equal to the one specified |
| `maxId` | `*int` | Query, Optional | Returns events with an id less than or equal to the one specified |
| `sinceId` | `*int64` | Query, Optional | Returns events with an id greater than or equal to the one specified |
| `maxId` | `*int64` | Query, Optional | Returns events with an id less than or equal to the one specified |
| `direction` | [`*models.Direction`](../../doc/models/direction.md) | Query, Optional | The sort direction of the returned events. |
| `filter` | [`[]models.EventType`](../../doc/models/event-type.md) | Query, Optional | You can pass multiple event keys after comma.<br>Use in query `filter=signup_success,payment_success`. |
| `dateField` | [`*models.ListEventsDateField`](../../doc/models/list-events-date-field.md) | Query, Optional | The type of filter you would like to apply to your search. |
Expand Down Expand Up @@ -218,8 +218,8 @@ ListSubscriptionEvents(
| `subscriptionId` | `int` | Template, Required | The Chargify id of the subscription |
| `page` | `*int` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.<br>Use in query `page=1`. |
| `perPage` | `*int` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.<br>Use in query `per_page=200`. |
| `sinceId` | `*int` | Query, Optional | Returns events with an id greater than or equal to the one specified |
| `maxId` | `*int` | Query, Optional | Returns events with an id less than or equal to the one specified |
| `sinceId` | `*int64` | Query, Optional | Returns events with an id greater than or equal to the one specified |
| `maxId` | `*int64` | Query, Optional | Returns events with an id less than or equal to the one specified |
| `direction` | [`*models.Direction`](../../doc/models/direction.md) | Query, Optional | The sort direction of the returned events. |
| `filter` | [`[]models.EventType`](../../doc/models/event-type.md) | Query, Optional | You can pass multiple event keys after comma.<br>Use in query `filter=signup_success,payment_success`. |

Expand Down Expand Up @@ -315,8 +315,8 @@ ReadEventsCount(
| --- | --- | --- | --- |
| `page` | `*int` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.<br>Use in query `page=1`. |
| `perPage` | `*int` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.<br>Use in query `per_page=200`. |
| `sinceId` | `*int` | Query, Optional | Returns events with an id greater than or equal to the one specified |
| `maxId` | `*int` | Query, Optional | Returns events with an id less than or equal to the one specified |
| `sinceId` | `*int64` | Query, Optional | Returns events with an id greater than or equal to the one specified |
| `maxId` | `*int64` | Query, Optional | Returns events with an id less than or equal to the one specified |
| `direction` | [`*models.Direction`](../../doc/models/direction.md) | Query, Optional | The sort direction of the returned events. |
| `filter` | [`[]models.EventType`](../../doc/models/event-type.md) | Query, Optional | You can pass multiple event keys after comma.<br>Use in query `filter=signup_success,payment_success`. |

Expand Down
2 changes: 1 addition & 1 deletion doc/controllers/invoices.md
Original file line number Diff line number Diff line change
Expand Up @@ -655,7 +655,7 @@ ListInvoiceEvents(
| Parameter | Type | Tags | Description |
| --- | --- | --- | --- |
| `sinceDate` | `*string` | Query, Optional | The timestamp in a format `YYYY-MM-DD T HH:MM:SS Z`, or `YYYY-MM-DD`(in this case, it returns data from the beginning of the day). of the event from which you want to start the search. All the events before the `since_date` timestamp are not returned in the response. |
| `sinceId` | `*int` | Query, Optional | The ID of the event from which you want to start the search(ID is not included. e.g. if ID is set to 2, then all events with ID 3 and more will be shown) This parameter is not used if since_date is defined. |
| `sinceId` | `*int64` | Query, Optional | The ID of the event from which you want to start the search(ID is not included. e.g. if ID is set to 2, then all events with ID 3 and more will be shown) This parameter is not used if since_date is defined. |
| `page` | `*int` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.<br>Use in query `page=1`. |
| `perPage` | `*int` | Query, Optional | This parameter indicates how many records to fetch in each request. Default value is 100. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. |
| `invoiceUid` | `*string` | Query, Optional | Providing an invoice_uid allows for scoping of the invoice events to a single invoice or credit note. |
Expand Down
2 changes: 1 addition & 1 deletion doc/controllers/product-families.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ ctx := context.Background()

body := models.CreateProductFamilyRequest{
ProductFamily: models.CreateProductFamily{
Name: models.ToPointer("Acme Projects"),
Name: "Acme Projects",
Description: models.NewOptional(models.ToPointer("Amazing project management tool")),
},
}
Expand Down
6 changes: 4 additions & 2 deletions doc/controllers/subscription-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,7 @@ ListSubscriptionComponents(
| `startDate` | `*string` | Query, Optional | The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. |
| `startDatetime` | `*string` | Query, Optional | The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. |
| `include` | [`[]models.ListSubscriptionComponentsInclude`](../../doc/models/list-subscription-components-include.md) | Query, Optional | Allows including additional data in the response. Use in query `include=subscription,historic_usages`. |
| `inUse` | `*bool` | Query, Optional | If in_use is set to true, it returns only components that are currently in use. However, if it's set to false or not provided, it returns all components connected with the subscription. |

## Response Type

Expand Down Expand Up @@ -160,6 +161,7 @@ collectedInput := advancedbilling.ListSubscriptionComponentsInput{
models.ListSubscriptionComponentsInclude("subscription"),
models.ListSubscriptionComponentsInclude("historic_usages"),
},
InUse: models.ToPointer(true),
}

apiResponse, err := subscriptionComponentsController.ListSubscriptionComponents(ctx, collectedInput)
Expand Down Expand Up @@ -1272,8 +1274,8 @@ ListUsages(
| --- | --- | --- | --- |
| `subscriptionId` | `int` | Template, Required | The Chargify id of the subscription |
| `componentId` | [`models.ListUsagesInputComponentId`](../../doc/models/containers/list-usages-input-component-id.md) | Template, Required | This is a container for one-of cases. |
| `sinceId` | `*int` | Query, Optional | Returns usages with an id greater than or equal to the one specified |
| `maxId` | `*int` | Query, Optional | Returns usages with an id less than or equal to the one specified |
| `sinceId` | `*int64` | Query, Optional | Returns usages with an id greater than or equal to the one specified |
| `maxId` | `*int64` | Query, Optional | Returns usages with an id less than or equal to the one specified |
| `sinceDate` | `*time.Time` | Query, Optional | Returns usages with a created_at date greater than or equal to midnight (12:00 AM) on the date specified. |
| `untilDate` | `*time.Time` | Query, Optional | Returns usages with a created_at date less than or equal to midnight (12:00 AM) on the date specified. |
| `page` | `*int` | Query, Optional | Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.<br>Use in query `page=1`. |
Expand Down
2 changes: 1 addition & 1 deletion doc/models/apply-credit-note-event-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Example schema for an `apply_credit_note` event
| `OriginalAmount` | `string` | Required | The full, original amount of the credit note. |
| `AppliedAmount` | `string` | Required | The amount of the credit note applied to invoice. |
| `TransactionTime` | `*time.Time` | Optional | The time the credit note was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" |
| `Memo` | `*string` | Optional | The credit note memo. |
| `Memo` | `models.Optional[string]` | Optional | The credit note memo. |
| `Role` | `*string` | Optional | The role of the credit note (e.g. 'general') |
| `ConsolidatedInvoice` | `*bool` | Optional | Shows whether it was applied to consolidated invoice or not |
| `AppliedCreditNotes` | [`[]models.AppliedCreditNoteData`](../../doc/models/applied-credit-note-data.md) | Optional | List of credit notes applied to children invoices (if consolidated invoice) |
Expand Down
62 changes: 62 additions & 0 deletions doc/models/apply-credit-note-event.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@

# Apply Credit Note Event

## Structure

`ApplyCreditNoteEvent`

## Fields

| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `Id` | `int64` | Required | - |
| `Timestamp` | `time.Time` | Required | - |
| `Invoice` | [`models.Invoice`](../../doc/models/invoice.md) | Required | - |
| `EventType` | [`models.InvoiceEventType`](../../doc/models/invoice-event-type.md) | Required | **Default**: `"apply_credit_note"` |
| `EventData` | [`models.ApplyCreditNoteEventData`](../../doc/models/apply-credit-note-event-data.md) | Required | Example schema for an `apply_credit_note` event |

## Example (as JSON)

```json
{
"id": 214,
"timestamp": "2016-03-13T12:52:32.123Z",
"invoice": {
"issue_date": "2024-01-01",
"due_date": "2024-01-01",
"paid_date": "2024-01-01",
"id": 166,
"uid": "uid6",
"site_id": 92,
"customer_id": 204,
"subscription_id": 20
},
"event_type": "apply_credit_note",
"event_data": {
"uid": "uid6",
"credit_note_number": "credit_note_number0",
"credit_note_uid": "credit_note_uid0",
"original_amount": "original_amount0",
"applied_amount": "applied_amount2",
"transaction_time": "2016-03-13T12:52:32.123Z",
"memo": "memo0",
"role": "role0",
"consolidated_invoice": false,
"applied_credit_notes": [
{
"uid": "uid4",
"number": "number8"
},
{
"uid": "uid4",
"number": "number8"
},
{
"uid": "uid4",
"number": "number8"
}
]
}
}
```

6 changes: 5 additions & 1 deletion doc/models/apply-debit-note-event-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Example schema for an `apply_debit_note` event
| `DebitNoteUid` | `string` | Required | Unique identifier for the debit note. It is generated automatically by Chargify and has the prefix "db_" followed by alphanumeric characters. |
| `OriginalAmount` | `string` | Required | The full, original amount of the debit note. |
| `AppliedAmount` | `string` | Required | The amount of the debit note applied to invoice. |
| `Memo` | `models.Optional[string]` | Optional | The debit note memo. |
| `TransactionTime` | `models.Optional[time.Time]` | Optional | The time the debit note was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" |

## Example (as JSON)

Expand All @@ -23,7 +25,9 @@ Example schema for an `apply_debit_note` event
"debit_note_number": "debit_note_number0",
"debit_note_uid": "debit_note_uid6",
"original_amount": "original_amount4",
"applied_amount": "applied_amount8"
"applied_amount": "applied_amount8",
"memo": "memo4",
"transaction_time": "2016-03-13T12:52:32.123Z"
}
```

45 changes: 45 additions & 0 deletions doc/models/apply-debit-note-event.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@

# Apply Debit Note Event

## Structure

`ApplyDebitNoteEvent`

## Fields

| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `Id` | `int64` | Required | - |
| `Timestamp` | `time.Time` | Required | - |
| `Invoice` | [`models.Invoice`](../../doc/models/invoice.md) | Required | - |
| `EventType` | [`models.InvoiceEventType`](../../doc/models/invoice-event-type.md) | Required | **Default**: `"apply_debit_note"` |
| `EventData` | [`models.ApplyDebitNoteEventData`](../../doc/models/apply-debit-note-event-data.md) | Required | Example schema for an `apply_debit_note` event |

## Example (as JSON)

```json
{
"id": 164,
"timestamp": "2016-03-13T12:52:32.123Z",
"invoice": {
"issue_date": "2024-01-01",
"due_date": "2024-01-01",
"paid_date": "2024-01-01",
"id": 166,
"uid": "uid6",
"site_id": 92,
"customer_id": 204,
"subscription_id": 20
},
"event_type": "apply_debit_note",
"event_data": {
"debit_note_number": "debit_note_number6",
"debit_note_uid": "debit_note_uid2",
"original_amount": "original_amount0",
"applied_amount": "applied_amount2",
"memo": "memo0",
"transaction_time": "2016-03-13T12:52:32.123Z"
}
}
```

4 changes: 3 additions & 1 deletion doc/models/apply-payment-event-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,12 @@ Example schema for an `apply_payment` event

| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `ConsolidationLevel` | [`models.InvoiceConsolidationLevel`](../../doc/models/invoice-consolidation-level.md) | Required | - |
| `Memo` | `string` | Required | The payment memo |
| `OriginalAmount` | `string` | Required | The full, original amount of the payment transaction as a string in full units. Incoming payments can be split amongst several invoices, which will result in a `applied_amount` less than the `original_amount`. Example: A $100.99 payment, of which $40.11 is applied to this invoice, will have an `original_amount` of `"100.99"`. |
| `AppliedAmount` | `string` | Required | The amount of the payment applied to this invoice. Incoming payments can be split amongst several invoices, which will result in a `applied_amount` less than the `original_amount`. Example: A $100.99 payment, of which $40.11 is applied to this invoice, will have an `applied_amount` of `"40.11"`. |
| `TransactionTime` | `time.Time` | Required | The time the payment was applied, in ISO 8601 format, i.e. "2019-06-07T17:20:06Z" |
| `PaymentMethod` | [`models.InvoiceEventPayment2`](../../doc/models/containers/invoice-event-payment-2.md) | Required | A nested data structure detailing the method of payment |
| `PaymentMethod` | [`models.InvoiceEventPayment`](../../doc/models/containers/invoice-event-payment.md) | Required | A nested data structure detailing the method of payment |
| `TransactionId` | `*int` | Optional | The Chargify id of the original payment |
| `ParentInvoiceNumber` | `models.Optional[int]` | Optional | - |
| `RemainingPrepaymentAmount` | `models.Optional[string]` | Optional | - |
Expand All @@ -26,6 +27,7 @@ Example schema for an `apply_payment` event

```json
{
"consolidation_level": "child",
"memo": "memo8",
"original_amount": "original_amount8",
"applied_amount": "applied_amount4",
Expand Down
52 changes: 52 additions & 0 deletions doc/models/apply-payment-event.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@

# Apply Payment Event

## Structure

`ApplyPaymentEvent`

## Fields

| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `Id` | `int64` | Required | - |
| `Timestamp` | `time.Time` | Required | - |
| `Invoice` | [`models.Invoice`](../../doc/models/invoice.md) | Required | - |
| `EventType` | [`models.InvoiceEventType`](../../doc/models/invoice-event-type.md) | Required | **Default**: `"apply_payment"` |
| `EventData` | [`models.ApplyPaymentEventData`](../../doc/models/apply-payment-event-data.md) | Required | Example schema for an `apply_payment` event |

## Example (as JSON)

```json
{
"id": 234,
"timestamp": "2016-03-13T12:52:32.123Z",
"invoice": {
"issue_date": "2024-01-01",
"due_date": "2024-01-01",
"paid_date": "2024-01-01",
"id": 166,
"uid": "uid6",
"site_id": 92,
"customer_id": 204,
"subscription_id": 20
},
"event_type": "apply_payment",
"event_data": {
"consolidation_level": "child",
"memo": "memo0",
"original_amount": "original_amount0",
"applied_amount": "applied_amount2",
"transaction_time": "2016-03-13T12:52:32.123Z",
"payment_method": {
"type": "apple_pay"
},
"transaction_id": 78,
"parent_invoice_number": 36,
"remaining_prepayment_amount": "remaining_prepayment_amount6",
"prepayment": false,
"external": false
}
}
```

Loading

0 comments on commit f7506c5

Please sign in to comment.