AccountingPeriod

Last updated
Save as PDF

Use the AccountingPeriod object to create accounting periods. This reference describes the SOAP API object including supported calls, required permissions, and field descriptions. Examples are also provided.

Accounting Periods

Accounting periods match your financial periods. Zuora aligns your transactions to your accounting periods, and shows you the history of how your business performs across multiple accounting periods. An accounting period holds the information you need to perform your company's bookkeeping activities, especially tracking and reporting financial activities such as earnings, expenses, and taxes. You create accounting periods in Z-Finance to encompass the financial transactions during your company's accounting period, then close the accounting period per your company's specified time. Closing an accounting period in Zuora is like closing the books.

You create accounting periods to close the books and report on financial activities.

Supported Calls

You can use this object with the following calls:

Permissions

Access to Z-Finance is required for all interactions.

You need the Create Accounting Period permission to update the following fields:

Name
StartDate
EndDate
Notes
FiscalYear
CustomFields

You need the Manage Close Process and Run Trial Balance permissions to update the Status field value from Open to Closed.

You need the Reopen Accounting Period permission to reopen an accounting period, which updates the Status field value from Closed to Open.

You need the Delete Accounting Period permission to delete an accounting code.

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name	Required to Create?	Allowed Operations	Description
CreatedById	Optional	Query	The identifier of the user who created the accounting code. Type: string ID Character limit: N/A Version: WSDL 50.0+ Z-Finance Required: No
CreatedDate	Optional	Query	The date when the accounting code was created. Type: dateTime Character limit: N/A Version: WSDL 50.0+ Z-Finance Required: No
EndDate	required	Create Query Update Filter	The end date of the accounting period. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Character limit: Version notes: Z-Finance
FiscalQuarter	optional	Create Query Update Filter	The fiscal quarter of the accounting period. Type: int Character limit: Version notes: WSDL 81.0+ Values: The default value is null. Supported values are: 1, 2, 3, and 4.
FiscalYear	required	Create Query Update Filter	The fiscal year for the accounting period. Type: int Character limit: Version notes: Z-Finance Values: a valid integer of the form, YYYY
Id	optional	Query Filter	The ID of this object. Upon creation of this object, this field becomes AccountingPeriodId. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated
Name	required	Create Query Update Filter	The name of the accounting period, which is displayed on the list of accounting periods on the All Accounting Periods page. Type: string Character limit:100 Version notes: Z-Finance Values: a string of 100 characters or fewer
Notes	optional	Create Query Update Filter	Use this field to record comments about the accounting period. Type: string Character limit: 255 Version notes: Z-Finance Values: a string of 255 characters or fewer
Status	required	Query Update Filter	The status of the accounting period. Type: string Character limit: 6 Version notes: Z-Finance Allowable values: automatically generated on creattion; one of the following values: Open Closed
StartDate	required	Create Query Update Filter	The start date of the accounting period. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Character limit: 29 Version notes: Z-Finance Values: automatically generated after the first accounting period
UpdatedById	Optional	Query	The identifier of the user who created the accounting code. Type: string ID Character limit: N/A Version: WSDL 50.0+ Z-Finance Required: No
UpdatedDate	Optional	Query	The date when the accounting code was updated. Type: dateTime Character limit: N/A Version: WSDL 50.0+ Z-Finance Required: No

Additional Field Detail

EndDate

You can update the end date only for your open accounting periods.

When you update the end date of an accounting period, then the start date of the next accounting period is automatically updated to the day after the new end date. For example:

The accounting period, August 2012, starts on 08/01/2012 and ends on 08/30/2012. The accounting period, September 2012, starts on 08/31/2012 and ends on 09/29/2012. You change the end date of August 2012 to 08/31/2012. The start date of September 2012 automatically changes to 09/01/2012.

Any existing trial balance results are removed when you alter the dates of accounting periods.

The accounting period history is updated when you change it. If you change dates, then the history of the accounting period you edited and the histories of the accounting periods that automatically change are also updated.

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscriptionobject's ID with the call.

The ID for the AccountingPeriod object is AccountingPeriodId.

StartDate

You can update the start date only for your first accounting period. The StartDate field is available to you only the first time the very first accounting period is created. After the first accounting period is created, subsequent accounting periods automatically start the day after the most recent end date.

Status

The status of the accounting period is automatically generated as Open when you create an accounting period.

When you run a query() call against the Status field, the value can be one of the following:

Open: The accounting period is open, and transactions can be recorded in the period. A new accounting period always starts in Open status.
Closed: The accounting period is locked down. You can change only the values in the Name, Notes, and FiscalYear fields. To make any other changes, you must reopen the accounting period.

An API call that updates the Status field cannot update any other fields.

Examples

Create an accounting period

AccountingPeriod ap = new AccountingPeriod();
ap.setName(AP_NAME);
ap.setStartDate(startDate);
ap.setEndDate(endDate);
ap.setNotes(AP_NOTES);
ap.setFiscalYear(YEAR);
create(ap);

Create an accounting period using a SOAP wrapper


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.zuora.com/" xmlns:obj="http://object.api.zuora.com/">
   <soapenv:Header>
      <api:SessionHeader>
         <api:session>{replace with your session}</api:session>
      </api:SessionHeader>
      <api:CallOptions>
         <!--Optional:-->
         <api:useSingleTransaction>?</api:useSingleTransaction>
      </api:CallOptions>
   </soapenv:Header>
   <soapenv:Body>
     <ns1:create xmlns:ns1="http://api.zuora.com/">
<ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
<ns2:Name>apFromAPI16</ns2:Name>
<ns2:StartDate>2011-08-10</ns2:StartDate>
<ns2:EndDate>2011-08-10</ns2:EndDate>
<ns2:Notes>ap notes from api</ns2:Notes>
<ns2:FiscalYear>2011</ns2:FiscalYear>
<ns2:FiscalQuarter>3</ns2FiscalQuarter>
</ns1:zObjects>
</ns1:create>
   </soapenv:Body>
</soapenv:Envelope>

Query an accounting period

String zql = "select EndDate, Name, Notes, Status, StartDate, FiscalYear from AccountingPeriod where id = '402892a133d3ff8b0133d4bf63070022'";
AccountingPeriod ap = (AccountingPeriod) queryOne(zql);

Query an accounting period with a SOAP wrapper

<?xml version="1.0" encoding="http://schemas.xmlsoap.org/soap/envelope/" standalone="no"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>{replace with your session}</ns1:session>
    </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:query xmlns:ns1="http://api.zuora.com/">
            <ns1:queryString>
            select id, CreatedById, CreatedDate, EndDate, Name, Notes, Status, StartDate, UpdatedById, UpdatedDate, FiscalYear, FiscalQuarter from AccountingPeriod where id = ' 4028929f33ca990b0133ca9ed8400002'
            </ns1:queryString>
        </ns1:query>
    </soapenv:Body>
</soapenv:Envelope>

Updating an accounting period with a SOAP wrapper

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>[replace with your session]</ns1:session>
    </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:update xmlns:ns1="http://api.zuora.com/">
            <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
                <ns2:Id>402892a837113da60137113ee28901a9</ns2:Id>
            <ns2:EndDate>2012-02-15</ns2:EndDate>
            <ns2:FiscalYear>2013</ns2:FiscalYear>
            <ns2:FiscalQuarter>1</ns2FiscalQuarter>
            <ns2:Name>update name</ns2:Name>
            <ns2:Notes>update notes</ns2:Notes>
            <ns2:StartDate>2012-01-15</ns2:StartDate>
        </ns1:zObjects>
        </ns1:update>
    </soapenv:Body>
</soapenv:Envelope>

Closing an accounting period with a SOAP wrapper

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>[replace with your session]</ns1:session>
    </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:update xmlns:ns1="http://api.zuora.com/">
            <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
            <ns2:Id>402892a83711418b01371142cc5801a9</ns2:Id>
            <ns2:Status>Closed</ns2:Status>
        </ns1:zObjects>
        </ns1:update>
    </soapenv:Body>
</soapenv:Envelope>

Reopening an accounting period with a SOAP wrapper

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <ns1:SessionHeader xmlns:ns1="http://api.zuora.com/" soapenv:mustUnderstand="0">
            <ns1:session>[replace with your session]</ns1:session>
        </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <ns1:update xmlns:ns1="http://api.zuora.com/">
            <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:AccountingPeriod">
            <ns2:Id>402892a83711442701371145625d01a9</ns2:Id>
            <ns2:Status>Open</ns2:Status>
        </ns1:zObjects>
        </ns1:update>
    </soapenv:Body>
</soapenv:Envelope>