Proforma Invoices

proformaInvoicesController := client.ProformaInvoicesController()

Class Name

ProformaInvoicesController

Methods

Create Consolidated Proforma Invoice
List Subscription Group Proforma Invoices
Read Proforma Invoice
Create Proforma Invoice
List Proforma Invoices
Void Proforma Invoice
Preview Proforma Invoice
Create Signup Proforma Invoice
Preview Signup Proforma Invoice

Create Consolidated Proforma Invoice

This endpoint will trigger the creation of a consolidated proforma invoice asynchronously. It will return a 201 with no message, or a 422 with any errors. To find and view the new consolidated proforma invoice, you may poll the subscription group listing for proforma invoices; only one consolidated proforma invoice may be created per group at a time.

If the information becomes outdated, simply void the old consolidated proforma invoice and generate a new one.

Restrictions

Proforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be prepaid, and must be in a live state.

CreateConsolidatedProformaInvoice(
    ctx context.Context,
    uid string) (
    http.Response,
    error)

Parameters

Parameter	Type	Tags	Description
`uid`	`string`	Template, Required	The uid of the subscription group

Response Type

``

Example Usage

ctx := context.Background()

uid := "uid0"

resp, err := proformaInvoicesController.CreateConsolidatedProformaInvoice(ctx, uid)
if err != nil {
    log.Fatalln(err)
} else {
    fmt.Println(resp.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
422	Unprocessable Entity (WebDAV)	`ErrorListResponseException`

List Subscription Group Proforma Invoices

Only proforma invoices with a consolidation_level of parent are returned.

By default, proforma invoices returned on the index will only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, custom_fields. To include breakdowns, pass the specific field as a key in the query with a value set to true.

ListSubscriptionGroupProformaInvoices(
    ctx context.Context,
    input ListSubscriptionGroupProformaInvoicesInput) (
    models.ApiResponse[models.ListProformaInvoicesResponse],
    error)

Parameters

Parameter	Type	Tags	Description
`uid`	`string`	Template, Required	The uid of the subscription group
`lineItems`	`*bool`	Query, Optional	Include line items data
`discounts`	`*bool`	Query, Optional	Include discounts data
`taxes`	`*bool`	Query, Optional	Include taxes data
`credits`	`*bool`	Query, Optional	Include credits data
`payments`	`*bool`	Query, Optional	Include payments data
`customFields`	`*bool`	Query, Optional	Include custom fields data

Response Type

models.ListProformaInvoicesResponse

Example Usage

ctx := context.Background()

collectedInput := advancedbilling.ListSubscriptionGroupProformaInvoicesInput{
    Uid:          "uid0",
    LineItems:    models.ToPointer(false),
    Discounts:    models.ToPointer(false),
    Taxes:        models.ToPointer(false),
    Credits:      models.ToPointer(false),
    Payments:     models.ToPointer(false),
    CustomFields: models.ToPointer(false),
}

apiResponse, err := proformaInvoicesController.ListSubscriptionGroupProformaInvoices(ctx, collectedInput)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
404	Not Found	`ApiError`

Read Proforma Invoice

Use this endpoint to read the details of an existing proforma invoice.

Restrictions

Proforma invoices are only available on Relationship Invoicing sites.

ReadProformaInvoice(
    ctx context.Context,
    proformaInvoiceUid string) (
    models.ApiResponse[models.ProformaInvoice],
    error)

Parameters

Parameter	Type	Tags	Description
`proformaInvoiceUid`	`string`	Template, Required	The uid of the proforma invoice

Response Type

models.ProformaInvoice

Example Usage

ctx := context.Background()

proformaInvoiceUid := "proforma_invoice_uid4"

apiResponse, err := proformaInvoicesController.ReadProformaInvoice(ctx, proformaInvoiceUid)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
404	Not Found	`ApiError`

Create Proforma Invoice

This endpoint will create a proforma invoice and return it as a response. If the information becomes outdated, simply void the old proforma invoice and generate a new one.

If you would like to preview the next billing amounts without generating a full proforma invoice, please use the renewal preview endpoint.

Restrictions

Proforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be in a group, must not be prepaid, and must be in a live state.

CreateProformaInvoice(
    ctx context.Context,
    subscriptionId int) (
    models.ApiResponse[models.ProformaInvoice],
    error)

Parameters

Parameter	Type	Tags	Description
`subscriptionId`	`int`	Template, Required	The Chargify id of the subscription

Response Type

models.ProformaInvoice

Example Usage

ctx := context.Background()

subscriptionId := 222

apiResponse, err := proformaInvoicesController.CreateProformaInvoice(ctx, subscriptionId)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
422	Unprocessable Entity (WebDAV)	`ErrorListResponseException`

List Proforma Invoices

By default, proforma invoices returned on the index will only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, or custom_fields. To include breakdowns, pass the specific field as a key in the query with a value set to true.

ListProformaInvoices(
    ctx context.Context,
    input ListProformaInvoicesInput) (
    models.ApiResponse[models.ListProformaInvoicesResponse],
    error)

Parameters

Parameter	Type	Tags	Description
`subscriptionId`	`int`	Template, Required	The Chargify id of the subscription
`startDate`	`*string`	Query, Optional	The beginning date range for the invoice's Due Date, in the YYYY-MM-DD format.
`endDate`	`*string`	Query, Optional	The ending date range for the invoice's Due Date, in the YYYY-MM-DD format.
`status`	`*models.ProformaInvoiceStatus`	Query, Optional	The current status of the invoice. Allowed Values: draft, open, paid, pending, voided
`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. 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. Use in query `per_page=200`.
`direction`	`*models.Direction`	Query, Optional	The sort direction of the returned invoices.
`lineItems`	`*bool`	Query, Optional	Include line items data
`discounts`	`*bool`	Query, Optional	Include discounts data
`taxes`	`*bool`	Query, Optional	Include taxes data
`credits`	`*bool`	Query, Optional	Include credits data
`payments`	`*bool`	Query, Optional	Include payments data
`customFields`	`*bool`	Query, Optional	Include custom fields data

Response Type

models.ListProformaInvoicesResponse

Example Usage

ctx := context.Background()

collectedInput := advancedbilling.ListProformaInvoicesInput{
    SubscriptionId: 222,
    Page:           models.ToPointer(2),
    PerPage:        models.ToPointer(50),
    Direction:      models.ToPointer(models.Direction("desc")),
    LineItems:      models.ToPointer(false),
    Discounts:      models.ToPointer(false),
    Taxes:          models.ToPointer(false),
    Credits:        models.ToPointer(false),
    Payments:       models.ToPointer(false),
    CustomFields:   models.ToPointer(false),
}

apiResponse, err := proformaInvoicesController.ListProformaInvoices(ctx, collectedInput)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Void Proforma Invoice

This endpoint will void a proforma invoice that has the status "draft".

Restrictions

Proforma invoices are only available on Relationship Invoicing sites.

Only proforma invoices that have the appropriate status may be reopened. If the invoice identified by {uid} does not have the appropriate status, the response will have HTTP status code 422 and an error message.

A reason for the void operation is required to be included in the request body. If one is not provided, the response will have HTTP status code 422 and an error message.

VoidProformaInvoice(
    ctx context.Context,
    proformaInvoiceUid string,
    body *models.VoidInvoiceRequest) (
    models.ApiResponse[models.ProformaInvoice],
    error)

Parameters

Parameter	Type	Tags	Description
`proformaInvoiceUid`	`string`	Template, Required	The uid of the proforma invoice
`body`	`*models.VoidInvoiceRequest`	Body, Optional	-

Response Type

models.ProformaInvoice

Example Usage

ctx := context.Background()

proformaInvoiceUid := "proforma_invoice_uid4"



apiResponse, err := proformaInvoicesController.VoidProformaInvoice(ctx, proformaInvoiceUid, nil)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
404	Not Found	`ApiError`
422	Unprocessable Entity (WebDAV)	`ErrorListResponseException`

Preview Proforma Invoice

Return a preview of the data that will be included on a given subscription's proforma invoice if one were to be generated. It will have similar line items and totals as a renewal preview, but the response will be presented in the format of a proforma invoice. Consequently it will include additional information such as the name and addresses that will appear on the proforma invoice.

The preview endpoint is subject to all the same conditions as the proforma invoice endpoint. For example, previews are only available on the Relationship Invoicing architecture, and previews cannot be made for end-of-life subscriptions.

If all the data returned in the preview is as expected, you may then create a static proforma invoice and send it to your customer. The data within a preview will not be saved and will not be accessible after the call is made.

Alternatively, if you have some proforma invoices already, you may make a preview call to determine whether any billing information for the subscription's upcoming renewal has changed.

PreviewProformaInvoice(
    ctx context.Context,
    subscriptionId int) (
    models.ApiResponse[models.ProformaInvoice],
    error)

Parameters

Parameter	Type	Tags	Description
`subscriptionId`	`int`	Template, Required	The Chargify id of the subscription

Response Type

models.ProformaInvoice

Example Usage

ctx := context.Background()

subscriptionId := 222

apiResponse, err := proformaInvoicesController.PreviewProformaInvoice(ctx, subscriptionId)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
404	Not Found	`ApiError`
422	Unprocessable Entity (WebDAV)	`ErrorListResponseException`

Create Signup Proforma Invoice

This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoices or preview prepaid subscriptions.

Create a proforma invoice to preview costs before a subscription's signup. Like other proforma invoices, it can be emailed to the customer, voided, and publicly viewed on the chargifypay domain.

Pass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address.

A product and customer first name, last name, and email are the minimum requirements. We recommend associating the proforma invoice with a customer_id to easily find their proforma invoices, since the subscription_id will always be blank.

CreateSignupProformaInvoice(
    ctx context.Context,
    body *models.CreateSubscriptionRequest) (
    models.ApiResponse[models.ProformaInvoice],
    error)

Parameters

Parameter	Type	Tags	Description
`body`	`*models.CreateSubscriptionRequest`	Body, Optional	-

Response Type

models.ProformaInvoice

Example Usage

ctx := context.Background()

body := models.CreateSubscriptionRequest{
    Subscription: models.CreateSubscription{
        ProductHandle:                     models.ToPointer("gold-product"),
        CustomerAttributes:                models.ToPointer(models.CustomerAttributes{
            FirstName:    models.ToPointer("Myra"),
            LastName:     models.ToPointer("Maisel"),
            Email:        models.ToPointer("mmaisel@example.com"),
        }),
    },
}

apiResponse, err := proformaInvoicesController.CreateSignupProformaInvoice(ctx, &body)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
400	Bad Request	`ProformaBadRequestErrorResponseException`
422	Unprocessable Entity (WebDAV)	`ErrorArrayMapResponseException`

Preview Signup Proforma Invoice

This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoice previews or preview prepaid subscriptions.

Create a signup preview in the format of a proforma invoice to preview costs before a subscription's signup. You have the option of optionally previewing the first renewal's costs as well. The proforma invoice preview will not be persisted.

Pass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address.

A product and customer first name, last name, and email are the minimum requirements.

PreviewSignupProformaInvoice(
    ctx context.Context,
    include *models.CreateSignupProformaPreviewInclude,
    body *models.CreateSubscriptionRequest) (
    models.ApiResponse[models.SignupProformaPreviewResponse],
    error)

Parameters

Parameter	Type	Tags	Description
`include`	`*models.CreateSignupProformaPreviewInclude`	Query, Optional	Choose to include a proforma invoice preview for the first renewal. Use in query `include=next_proforma_invoice`.
`body`	`*models.CreateSubscriptionRequest`	Body, Optional	-

Response Type

models.SignupProformaPreviewResponse

Example Usage

ctx := context.Background()



body := models.CreateSubscriptionRequest{
    Subscription: models.CreateSubscription{
        ProductHandle:                     models.ToPointer("gold-plan"),
        CustomerAttributes:                models.ToPointer(models.CustomerAttributes{
            FirstName:    models.ToPointer("first"),
            LastName:     models.ToPointer("last"),
            Email:        models.ToPointer("flast@example.com"),
        }),
    },
}

apiResponse, err := proformaInvoicesController.PreviewSignupProformaInvoice(ctx, nil, &body)
if err != nil {
    log.Fatalln(err)
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Errors

HTTP Status Code	Error Description	Exception Class
400	Bad Request	`ProformaBadRequestErrorResponseException`
422	Unprocessable Entity (WebDAV)	`ErrorArrayMapResponseException`

Files

proforma-invoices.md

Latest commit

History

proforma-invoices.md

File metadata and controls

Proforma Invoices

Class Name

Methods

Create Consolidated Proforma Invoice

Restrictions

Parameters

Response Type

Example Usage

Errors

List Subscription Group Proforma Invoices

Parameters

Response Type

Example Usage

Errors

Read Proforma Invoice

Restrictions

Parameters

Response Type

Example Usage

Errors

Create Proforma Invoice

Restrictions

Parameters

Response Type

Example Usage

Errors

List Proforma Invoices

Parameters

Response Type

Example Usage

Void Proforma Invoice

Restrictions

Parameters

Response Type

Example Usage

Errors

Preview Proforma Invoice

Parameters

Response Type

Example Usage

Errors

Create Signup Proforma Invoice

Parameters

Response Type

Example Usage

Errors

Preview Signup Proforma Invoice

Parameters

Response Type

Example Usage

Errors