Create Proforma Invoice for Subscription

Use this endpoint to create a new proforma invoice that reflects changes you want to make to a subscription.

To create a proforma invoice without any subscription changes, see Retrieve Proforma Invoice for Subscription.

Use Case: View proposed changes without proration

If you set prorate to false, FastSpring generates a proforma invoice that reflects changes that will take effect at the next renewal date, like in the following request:

{
    "subscription": "L8bCzkPQRn2lq4UEWJfiOA",
    "product": "subscription1montlyy",
    "prorate": false, // Prorate set to false.
    "quantity": 2,
    "language": "es",
    "pricing": {
        "price": {
            "USD": 200
        }
    }
}

{
  "invoice": {
    "id": "proforma12345",
    "subscription": "L8bCzkPQRn2lq4UEWJfiOA",
    "product": "subscription1montlyy",
    "quantity": 2,
    "total_price": {
      "USD": 200
    },
    "prorated": false,
    "language": "es",
    "created_at": "2024-06-23T12:34:56Z"
  },
  "proformaInvoiceHeader": {
    "currency": "USD",
    "timezone": "UTC",
    "language": "es",
    "message": "Esta factura y el monto en la proxima fecha de pago son validos siempre y cuando no haya cambios en el plan de suscripcion y/o los detalles de facturacion desde la fecha de hoy hasta la proxima fecha de cobro.",
    "logoUrl": "https://example.com/logo.png",
    "proFormaInvoiceCreationDate": 1656016000000,
    "proFormaInvoiceCreationDateDisplay": "06/23/24",
    "proFormaInvoiceCreationDateDisplayISO8601": "2024-06-23",
    "proFormaInvoiceExpirationDate": 1658617600000,
    "proFormaInvoiceExpirationDateDisplay": "06/30/24",
    "proFormaInvoiceExpirationDateDisplayISO8601": "2024-07-10"
  },
  "supportContact": {
    "name": "FastSpring Support",
    "email": "[email protected]",
    "url": "https://www.fastspring.com/support"
  },
  "merchantContact": {
    "merchantName": "FastSpring",
    "merchantAddress": "11 W Victoria St Suite 207A Santa Barbara, CA 93101 US"
  },
  "coTerm": {
    "account": "account123",
    "coTermGroupId": "coTermGroup123"
  },
  "contact": {
    "email": "[email protected]",
    "firstName": "John",
    "phone": "123-456-7890",
    "company": "Customer Company",
    "address": {
      "accountId": "account123",
      "addressLine1": "123 Main St",
      "city": "Anytown",
      "region": "CA",
      "postalCode": "12345",
      "country": "US"
    }
  },
  "items": {
    "subscription": "L8bCzkPQRn2lq4UEWJfiOA",
    "product": "subscription1monthly",
    "quantity": 2,
    "price": {
      "USD": 200
    }
  }
}

Use Case: View proposed changes with proration

If you set prorate to true, FastSpring generates a proforma invoice that reflects changes that will take effect immediately, like in the following request:

{
    "subscription": "L8bCzkPQRn2lq4UEWJfiOA",
    "product": "subscription1montlyy",
    "prorate": true, // Prorate set to true.
    "quantity": 2,
    "language": "es",
    "pricing": {
        "price": {
            "USD": 200
        }
    }
}

Because prorated invoices are based on the number of remaining days before the next renewal, the invoice that FastSpring generates is only valid for one day. The prorated amount will change as each day passes.

Error Handling

Status Code	Error Message	Solution
`400`	`Invalid request parameters`	Verify the body structure of your request. Make sure that you've included all required parameters.
`404`	`Subscription ID does not exist: [subscription_id]`	Verify that the subscription ID you're using is correct and exists in the system. Double-check for any typos in the ID.
`405`	`Subscription is in trial period: [subscription_id]`	Wait until the trial period for the subscription has ended before creating a proforma invoice.
`500`	`Exception getting subscription change estimate for sub_id:[subscription_id]`	Server-side error. Retry the request or contact FastSpring support if the issue persists.