GitHub - hyeomans/zuora: A go client library for Zuora API

A Go client library to consume Zuora API.

This is a WIP and has minimal endpoints covered but it is really easy to add new ones.

Requirements
Available endpoints
Missing types
Usage
ZOQL Queries
Production Copy Environment
Error handling

Requirements

Go >1.7
Zuora client ID (Use Environment variables as best practice)
Zuora client secret (Use Environment variables as best practice)
Zuora api url (Use Environment variables as best practice)
You can get a ClientId & ClientSecret at: https://labs.zuora.com/ for testing purposes

Available endpoints

Accounts:
- Get - /v1/accounts/{accountKey}
- Summary - /v1/accounts/{objectId}/summary
- Update - /v1/accounts/{accountKey}
Actions
- Query - /v1/action/query ZOQL queries
- Create - /v1/action/create Bulk action endpoint.
Catalog
- GetProduct - /v1/catalog/products?pageSize={pageSize}
- GetProductNextPage - Pass uri from GetProduct
Describe
- Model - /v1/describe/{objectModel} Helpful to see custom types and full properties
PaymentMethods
- GetPaymentMethod - /v1/object/payment-method/{objectID}
- GetPaymentMethodSnapshot - /v1/object/payment-method-snapshot/{snapshotID}
Subscription
- ByKey - /v1/subscriptions/{subscriptionKey}
- Update - /v1/subscriptions/{subscriptionKey}
- Cancel - /v1/subscriptions/{subscriptionKey}/cancel
Invoices
- GetInvoice - /v1/object/invoice/{invoiceID}
- GetInvoiceFiles - /v1/invoices/{InvoiceID}/files?pageSize={pageSize}
- GetInvoiceItems - /v1/invoices/%v/items?pageSize={pageSize}
Refund
- Create - /v1/object/refund

Missing types

Why return an array of bytes? Zuora responses vary from company to company. The variation comes from Custom Fields defined into your company definition of Zuora.

The package could send typed information, let's take the example of Product. Zuora defines "Product" entity like this:

type Product struct {
  AllowFeatureChanges *bool   `json:"AllowFeatureChanges,omitempty"`
  Category            *string `json:"Category,omitempty"`
  CreatedByID         *string `json:"CreatedById,omitempty"`
  CreatedDate         *string `json:"CreatedDate,omitempty"`
  Description         *string `json:"Description,omitempty"`
  EffectiveEndDate    string  `json:"EffectiveEndDate"`
  EffectiveStartDate  string  `json:"EffectiveStartDate"`
  ID                  *string `json:"Id,omitempty"`
  Name                string  `json:"Name"`
  SKU                 *string `json:"SKU,omitempty"`
  UpdatedByID         *string `json:"UpdatedById,omitempty"`
  UpdatedDate         *string `json:"UpdatedDate,omitempty"`
}

But, how would you define custom fields if the signature of the method is:

func (t *catalogService) GetProduct(ctx context.Context, pageSize int) (*Product, error) {....}

Well, you can't. That's why we return the raw bytes, and then you can marshal into your own struct. We include common types into the package, so you don't have to guess. Imagine you have a custom field named "DisplayName__c", you can define your own struct using the power of struct embedding. For example:

type myProduct struct {
  zuora.Product
  DisplayName     *string `json:"DisplayName__c,omitempty"`
}

Now marshal the JSON into your custom struct. Let's see a practical example with the Account Summary endpoint.

Usage

Account Summary Example

Account summary response retrieves a great overview of an account state. The problem is that if you defined custom properties, the nested payload would include those properties.

In the following code example, you will find custom structs that define those custom properties, that later will be bound to a custom struct.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

type myRatePlan struct {
	zuora.RatePlan
	MyCustomProperty *string            `json:"MyCustomProperty__c,omitempty"`
	RatePlanCharges  []myRatePlanCharge `json:"ratePlanCharges"`
}

type myRatePlanCharge struct {
	zuora.RatePlanCharge
	MyCustomProperty *string `json:"MyCustomProperty,omitempty"`
}

type mySubscription struct {
	zuora.Subscription
	MyCustomProperty *string      `json:"MyCustomProperty__c,omitempty"`
	RatePlans        []myRatePlan `json:"ratePlans"`
}

type myInvoice struct {
	zuora.Invoice
	MyCustomProperty *string `json:"MyCustomProperty__c,omitempty"`
}

type myAccount struct {
	zuora.Account
	DefaultPaymentMethod zuora.PaymentMethod `json:"defaultPaymentMethod"`
	MyCustomProperty     *string             `json:"MyCustomProperty__c,omitempty"`
}

type summary struct {
	BasicInfo     myAccount        `json:"basicInfo"`
	BillToContact zuora.Contact    `json:"billToContact"`
	SoldToContact zuora.Contact    `json:"soldToContact"`
	TaxInfo       zuora.Account    `json:"taxInfo"`
	Subscriptions []mySubscription `json:"subscriptions"`
	Invoices      []myInvoice      `json:"invoices"`
	Usage         []zuora.Usage    `json:"usage"`
	Payments      []zuora.Payment  `json:"payments"`
	Success       bool             `json:"success"`
}

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	r, err := zuoraAPI.V1.AccountsService.Summary(ctx, "accountIdFromYouZuoraInstance")

	if err != nil {
		log.Fatal(err)
	}
	s := summary{}

	if err = json.Unmarshal(r, &s); err != nil {
		log.Fatal(err)
	}

	fmt.Println(*s.TaxInfo.VATId)
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 3 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

You can apply this pattern to other endpoints, for example, "Subscriptions," "Products," or ZOQL calls to the Query endpoint.

Updating an Account

Updating an account through Zuora requires to send a custom JSON payload. According to documentation, it is only necessary to submit those properties that need to be changed.

This package also allows modifying custom properties. Here is an example:

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

type myAccountUpdate struct {
	zuora.AccountUpdate
	CustomField *string `json:"CustomField__c,omitempty"`
}

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	if err != nil {
		log.Fatal(err)
	}

	myAcc := myAccountUpdate{}

	tr := "My Custom Field"
	myAcc.CustomField = &tr
	myAcc.Name = "New Name"

	response, err := zuoraAPI.V1.AccountsService.Update(ctx, "AccountNumber", myAcc)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Done: %+v", response)
}

Updating a Subscription

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	mySub := zuora.SubscriptionUpdate{}
	note := "some notheeees"
	mySub.Notes = &note
	r, err := zuoraAPI.V1.SubscriptionsService.Update(ctx, "A-S000XXXXX", mySub)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v", r)
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 3 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

Cancelling a subscription

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	mySub := zuora.SubscriptionCancellation{InvoiceCollect: false, CancellationPolicy: "EndOfLastInvoicePeriod"}
	r, err := zuoraAPI.V1.SubscriptionsService.Cancel(ctx, "A-S000XXX00", mySub)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v", r)
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 3 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

ZOQL Queries

Some ZOQL queries that have been helpful in the past.

Getting Yearly Invoices

Returns the 50 most recent Invoices from now until the previous year.

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	lastYear := time.Now().UTC().AddDate(-1, 0, 0).Format("2006-01-02")

	zoqlQuery := fmt.Sprintf(`
	SELECT 
		accountId, 
		amount, 
		amountWithoutTax, 
		balance, 
		createdDate, 
		dueDate, 
		id, 
		invoiceDate, 
		invoiceNumber, 
		paymentAmount,
		postedDate, 
		refundAmount, 
		status, 
		targetDate, 
		taxAmount, 
		taxExemptAmount
	FROM Invoice 
	WHERE accountId='%s' and targetDate >= '%s'`, "A-S000XXXXX", lastYear)

	t, err := zuoraAPI.V1.ActionsService.Query(ctx, zoqlQuery)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(t))
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 10 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

Getting Expired Subscriptions with Zoql

Gets a list of Zuora subscriptions that are cancelled and whose TermEndDate is today.

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	today := time.Now().UTC().Format("2006-01-02")
	zoqlQuery := fmt.Sprintf(`select name from subscription where status = 'cancelled' and termEndDate = '%v'`, today)

	t, err := zuoraAPI.V1.ActionsService.Query(ctx, zoqlQuery)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(t))
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 10 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

Getting Invoice Payments

Get all payments associated with provided invoice id.

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	zuoraOAuthHeaderProvider := zuora.NewOAuthHeader(httpClient, &zuora.MemoryTokenStore{}, zuoraClientID, zuoraClientSecret, zuoraURL)
	zuoraAPI := zuora.NewAPI(httpClient, zuoraOAuthHeaderProvider, zuoraURL)

	invoiceID := "invoice-ID"
	zoqlQuery := fmt.Sprintf(`
	SELECT
		amount,
		createdDate,
		id,
		invoiceId,
		paymentId
	FROM invoicePayment
	WHERE invoiceId='%s'`, invoiceID)

	t, err := zuoraAPI.V1.ActionsService.Query(ctx, zoqlQuery)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(t))
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 10 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

Production Copy Environment

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"time"

	"github.com/hyeomans/zuora"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()

	if err != nil {
		log.Fatal("Error loading .env file")
	}

	ctx := context.Background()
	zuoraClientID := os.Getenv("ZUORA_CLIENT_ID")
	zuoraClientSecret := os.Getenv("ZUORA_CLIENT_SECRET")
	zuoraURL := os.Getenv("ZUORA_URL")
	httpClient := newHTTPClient()

	if err != nil {
		log.Fatal(err)
	}

	//zuoraClientID it's going to be the email
	//zuoraClientSecret it's going to be the plain password
	zuoraBasicAuth := zuora.NewBasicAuthHeader(zuoraClientID, zuoraClientSecret)
	zuoraAPI := zuora.NewPCEAPI(httpClient, zuoraBasicAuth, zuoraURL) //<---- Call NewPCEAPI instead of NewAPI.

	zoqlQuery := fmt.Sprintf(`select name, accountid from subscription`)
	r, err := zuoraAPI.V1.ActionsService.Query(ctx, zoqlQuery)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(r))
}

func newHTTPClient() *http.Client {
	keepAliveTimeout := 600 * time.Second
	timeout := 10 * time.Second
	defaultTransport := &http.Transport{
		Dial: (&net.Dialer{
			KeepAlive: keepAliveTimeout,
		}).Dial,
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 100,
	}

	return &http.Client{
		Transport: defaultTransport,
		Timeout:   timeout,
	}
}

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.gitignore		.gitignore
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
accounts.go		accounts.go
accounts_types.go		accounts_types.go
actions.go		actions.go
api.go		api.go
api_example_test.go		api_example_test.go
auth_headers.go		auth_headers.go
auth_headers_test.go		auth_headers_test.go
catalog.go		catalog.go
catalog_types.go		catalog_types.go
describe.go		describe.go
errors.go		errors.go
go.mod		go.mod
invoice_item_adjustment_types.go		invoice_item_adjustment_types.go
invoices.go		invoices.go
invoices_types.go		invoices_types.go
memory_token_store.go		memory_token_store.go
object_model.go		object_model.go
payment_methods.go		payment_methods.go
refund.go		refund.go
refund_types.go		refund_types.go
subscriptions.go		subscriptions.go
subscriptions_types.go		subscriptions_types.go
types.go		types.go

License

hyeomans/zuora

Folders and files

Latest commit

History

Repository files navigation

Requirements

Available endpoints

Missing types

Usage

Account Summary Example

Updating an Account

Updating a Subscription

Cancelling a subscription

ZOQL Queries

Getting Yearly Invoices

Getting Expired Subscriptions with Zoql

Getting Invoice Payments

Production Copy Environment

Error handling

About

Topics

Resources

License

Stars

Watchers

Forks

Languages